🔧 MySQL MCP Server

A Model Context Protocol (MCP) server for MySQL database operations. Supports two modes: Single Database and Multiple Databases.

✨ Features

• 🔀 Smart Mode - Automatically switches between single/multi database mode based on configuration
• 🔍 Execute SQL Queries - Run any SELECT, INSERT, UPDATE, DELETE commands
• 📊 List Databases - View all available databases (multi-db mode only)
• 📋 List Tables - Show tables in any database
• 🏗️ Describe Tables - Get detailed table structure information
• ⏱️ Connection Timeout - Configurable connection timeout (default 10s)
• 🔄 Auto Retry - Automatic retry on connection errors (default 2 retries)
• 💚 Keep-Alive - TCP keep-alive to prevent connection drops
• 🔒 Secure - Environment-based configuration, no hardcoded credentials
• ⚡ Fast - Built with TypeScript and connection pooling

🚀 Quick Start

Installation

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

# Install dependencies
npm install

# Build the project
npm run build

Configuration

The server uses environment variables for database configuration:

# Basic Configuration
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=                       # Database name (optional - see modes below)

# Connection Pool
DB_CONNECTION_LIMIT=3          # Connection pool size (default: 3)

# Timeout Configuration
DB_CONNECTION_TIMEOUT=10000    # Connection timeout in ms (default: 10000 = 10s)

# Keep-Alive Configuration
DB_KEEP_ALIVE_DELAY=30000      # TCP keep-alive delay in ms (default: 30000 = 30s)

# Retry Configuration
DB_MAX_RETRIES=2               # Max retry attempts (default: 2)
DB_RETRY_DELAY=1000            # Retry delay in ms (default: 1000 = 1s)

Modes

Single Database Mode (DB_NAME configured)

When DB_NAME is set, the server operates in single database mode:

• execute_sql only requires sql parameter
• list_tables requires no parameters
• describe_table only requires table parameter
• list_databases tool is NOT available

Multiple Databases Mode (DB_NAME not configured)

When DB_NAME is not set, the server operates in multi-database mode:

• execute_sql requires both database and sql parameters
• list_tables requires database parameter
• describe_table requires both database and table parameters
• list_databases tool is available

📖 Usage

With OpenCode

Add to your MCP configuration:

{
  "mcp": {
    "mysql": {
      "type": "local",
      "command": [
        "node",
        "/path/to/mysql-mcp-server/dist/index.js"
      ],
      "environment": {
        "DB_HOST": "your_mysql_host",
        "DB_PORT": "3306",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database"
      }
    }
  }
}

Replace the paths and credentials with your actual values.

With Claude Desktop

Add to your claude_desktop_config.json:

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

With Cursor IDE

Add to your MCP configuration:

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

🛠️ Available Tools

Single Database Mode

1. execute_sql

Execute any MySQL query.

Parameters:

• sql (required): SQL query to execute

Example:

{
  "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:

{
  "table": "users"
}

Multiple Databases Mode

1. list_databases

List all available databases on the MySQL server.

Parameters: None required

Example: {}

2. execute_sql

Execute any MySQL query on a specified database.

Parameters:

• database (required): Database name to execute the query on
• sql (required): SQL query to execute

Example:

{
  "database": "testdb",
  "sql": "SELECT * FROM users WHERE id = ?"
}

3. list_tables

List all tables in a specified database.

Parameters:

• database (required): Database name

Example:

{
  "database": "testdb"
}

4. describe_table

Get detailed information about a table's structure.

Parameters:

• database (required): Database name
• table (required): Table name to describe

Example:

{
  "database": "testdb",
  "table": "users"
}

🔧 Development

# 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/
├── 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.git

🙏 Acknowledgments

• Built with the Model Context Protocol SDK
• Uses mysql2 for MySQL connectivity
• Inspired by the MCP community

📞 Support

If you encounter any issues or have questions:

1. Check the 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