MySQL MCP Server

MySQL MCP Server

English | 简体中文

A Model Context Protocol (MCP) server implementation for MySQL databases, enabling AI assistants like Claude to interact with MySQL databases in a safe, standardized, and controlled way.

Features

• MCP Protocol Compliant: Fully implements the Model Context Protocol specification
• Safe Query Execution: Built-in query validation and safety controls
• Schema Inspection: Tools to explore database structure
• Transaction Support: Full transaction management (BEGIN, COMMIT, ROLLBACK)
• Resource Exposure: Database schemas exposed as MCP resources
• Comprehensive Error Handling: Detailed error messages with SQL state codes
• Property-Based Testing: Extensively tested with property-based testing for correctness

Installation

From Source

# Clone the repository
git clone <repository-url>
cd mysql-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (makes the command available system-wide)
npm link

After installation, the mysql-mcp-server command will be available system-wide.

Configuration

The server is configured entirely through environment variables:

Required Environment Variables

• MYSQL_HOST - MySQL server hostname (default: localhost)
• MYSQL_PORT - MySQL server port (default: 3306)
• MYSQL_USER - MySQL username (required)
• MYSQL_PASSWORD - MySQL password (required)
• MYSQL_DATABASE - Database name (required)

Optional Environment Variables

• MYSQL_CONNECTION_LIMIT - Maximum number of connections in pool (default: 10)
• MAX_SELECT_ROWS - Maximum rows returned by SELECT queries (default: 1000)
• ALLOW_DDL - Allow DDL operations (CREATE, DROP, ALTER) (default: false)
• ALLOW_MULTIPLE_STATEMENTS - Allow multiple SQL statements (default: false)
• REQUIRE_WHERE_CLAUSE - Require WHERE clause for UPDATE/DELETE (default: true)
• MCP_LOG_LEVEL - Logging level: debug, info, warn, error (default: info)

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-server",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

With Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project):

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-server",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

With npx (Direct Execution)

You can also run the server directly using npx without installation. First, build the project locally:

# In the project directory
npm run build

Then configure your MCP client to use npx with the local path:

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/mysql-mcp-server/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Available Tools

The server provides the following MCP tools:

1. `query`

Execute SQL queries (SELECT, INSERT, UPDATE, DELETE)

// Example usage in Claude
"Execute a query to find all users: SELECT * FROM users WHERE active = 1"

Safety Features:

• Automatically adds LIMIT to SELECT queries without one
• Rejects DELETE/UPDATE without WHERE clause (configurable)
• Rejects multiple statements
• Rejects DDL operations by default

2. `list_tables`

List all tables in the current database

// Example usage
"Show me all tables in the database"

3. `describe_table`

Get detailed schema information for a specific table

// Example usage
"Describe the structure of the users table"

4. `show_indexes`

Show all indexes for a specific table

// Example usage
"Show me the indexes on the orders table"

5. `begin_transaction`

Start a new database transaction

6. `commit_transaction`

Commit the current transaction

7. `rollback_transaction`

Rollback the current transaction

// Example transaction usage
"Start a transaction, update the user's email, then commit"

Available Resources

The server exposes database schemas as MCP resources:

• URI Format: mysql://{database}/{table}
• Content: Structured JSON with table schema information

// Example usage
"Read the schema resource for the users table"