npm package: @morris131/mysql-mcp-server-single
Description: MySQL MCP Server - stdio protocol for MySQL database operations with Windows support
Author: morris131
Latest version: 1.0.3

# 🔧 MySQL MCP Server

A Model Context Protocol (MCP) server for MySQL database operations. Provides 3 powerful tools for database interaction through any MCP-compatible client.

## ✨ Features
- **🔍 Execute SQL Queries** - Run any SELECT, INSERT, UPDATE, DELETE commands
- **📋 List Tables** - Show tables in the configured database
- **🏗️ Describe Tables** - Get detailed table structure information
- **🔒 Secure** - Environment-based configuration, no hardcoded credentials
- **⚡ Fast** - Built with TypeScript and connection pooling

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://gitee.com/morris131/mysql-mcp-server-single.git
cd mysql-mcp-server-single

# Install dependencies
npm install

# Build the project
npm run build
```

### Configuration

The server uses environment variables for database configuration:

```bash
DB_HOST=localhost              # MySQL host (default: 127.0.0.1)
DB_USER=root                  # MySQL username (default: root)
DB_PASSWORD=                  # MySQL password (default: empty)
DB_PORT=3306                  # MySQL port (default: 3306)
DB_NAME=your_database          # Database name (required)
DB_CONNECTION_LIMIT=3          # Connection pool size (default: 3)

# Connection timeout and retry settings
DB_CONNECTION_TIMEOUT=10000    # Connection acquisition timeout in ms (default: 10000)
DB_KEEP_ALIVE_DELAY=30000      # TCP keep-alive initial delay in ms (default: 30000)
DB_MAX_RETRIES=2               # Max retry attempts on connection error (default: 2)
DB_RETRY_DELAY=1000            # Delay between retries in ms (default: 1000)
```

## 📖 Usage

### With OpenCode

Add to your MCP configuration:

```json
{
  "mcp": {
    "mysql": {
      "type": "local",
      "command": [
        "node",
        "/path/to/mysql-mcp-server-single/dist/index.js"
      ],
      "environment": {
        "DB_HOST": "your_mysql_host",
        "DB_PORT": "3306",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "DB_CONNECTION_TIMEOUT": "10000",
        "DB_KEEP_ALIVE_DELAY": "30000",
        "DB_MAX_RETRIES": "2"
    }
  }
}
```

Replace the paths and credentials with your actual values.

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["path/to/mysql-mcp-server-single/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "3306",
        "DB_NAME": "your_database"
    }
  }
}
```

### With Cursor IDE

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["path/to/mysql-mcp-server-single/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "3306",
        "DB_NAME": "your_database"
    }
  }
}
```

## 🛠️ Available Tools

### 1. `execute_sql`
Execute any MySQL query on the configured database.

**Parameters:**
- `sql` (required): SQL query to execute (SELECT, INSERT, UPDATE, DELETE, etc.)
**Example:**
```json
{
  "sql": "SELECT * FROM users WHERE id = ?"
}

### 2. `list_tables`
List all tables in the configured database.
**Parameters:** None required
**Example:** `{}`

### 3. `describe_table`
Get detailed information about a table's structure.
**Parameters:**
- `table` (required): Table name to describe
**Example:**
```json
{
  "table": "users"
}

## 🔧 Development

```bash
# Install dependencies
npm install

# Development mode (watch for changes)
npm run dev

# Build for production
npm run build

# Start the server
npm start
```

## 📦 Project Structure

```
mysql-mcp-server-single/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (auto-generated)
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore rules
└── README.md            # This file
```

## 🔒 Security

- **No hardcoded credentials** - All database connection details come from environment variables
- **Connection pooling** - Efficient and secure database connections
- **Error handling** - Proper error messages without exposing sensitive information

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

**Repository:** https://gitee.com/morris131/mysql-mcp-server-single.git

## 🙏 Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Uses [mysql2](https://github.com/sidorares/node-mysql2) for MySQL connectivity
- Inspired by the MCP community

## 📞 Support

If you encounter any issues or have questions:

1. Check the [Issues](https://gitee.com/morris131/mysql-mcp-server-single/issues) page
2. Create a new issue if your problem isn't already reported
3. Provide as much detail as possible including error messages and configuration