Last updated January 4, 2026 - Production/Stable v2.1.0

📚 Full Documentation (Wiki) • Changelog • Security • Release Article

mysql-mcp is the definitive Model Context Protocol server for MySQL — empowering AI assistants like AntiGravity, Claude, Cursor, and other MCP clients with unparalleled database capabilities. Built for developers who demand enterprise-grade features without sacrificing ease of use.

• Node.js 18+
• MySQL 5.7+ or 8.0+ server
• npm or yarn

# Install globally
npm install -g @neverinfamous/mysql-mcp

# Run
mysql-mcp --transport stdio --mysql mysql://user:password@localhost:3306/database

# Or use npx without installing
npx @neverinfamous/mysql-mcp --transport stdio --mysql mysql://user:password@localhost:3306/database

docker run -i --rm writenotenow/mysql-mcp:latest \
  --transport stdio \
  --mysql mysql://user:[email protected]:3306/database

git clone https://github.com/neverinfamous/mysql-mcp.git
cd mysql-mcp
npm install
npm run build
node dist/cli.js --transport stdio --mysql mysql://user:password@localhost:3306/database

When to use HTTP mode: Use HTTP mode when deploying mysql-mcp as a standalone server that multiple clients can connect to remotely. For local development with Claude Desktop or Cursor IDE, use the default stdio mode shown below instead.

Use cases for HTTP mode:

• Running the server in a Docker container accessible over a network
• Deploying to cloud platforms (AWS, GCP, Azure)
• Enabling OAuth 2.1 authentication for enterprise security
• Allowing multiple AI clients to share one database connection

For enterprise deployments, mysql-mcp supports OAuth 2.1 authentication with Keycloak or any RFC-compliant provider.

1. Start with OAuth disabled (default)

mysql-mcp --mysql mysql://root:pass@localhost/db

2. Enable OAuth with an identity provider

mysql-mcp --mysql mysql://root:pass@localhost/db \
          --oauth-enabled \
          --oauth-issuer http://localhost:8080/realms/mysql-mcp \
          --oauth-audience mysql-mcp

Start the HTTP server:

# Local installation
node dist/cli.js --transport http --port 3000 --mysql mysql://user:password@localhost:3306/database

# Docker (expose port 3000)
docker run -p 3000:3000 writenotenow/mysql-mcp \
  --transport http \
  --port 3000 \
  --mysql mysql://user:[email protected]:3306/database

Available endpoints:

• GET /sse - Establish MCP connection via Server-Sent Events
• POST /messages - Send JSON-RPC messages to the server
• GET /health - Health check endpoint
• GET /.well-known/oauth-protected-resource - OAuth 2.1 metadata (when OAuth enabled)

💡 Tip: Most users should skip this section and use the stdio configuration below for local AI IDE integration.

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": [
        "C:/path/to/mysql-mcp/dist/cli.js",
        "--transport", "stdio",
        "--mysql", "mysql://user:password@localhost:3306/database"
      ]
    }
  }
}

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": [
        "C:/path/to/mysql-mcp/dist/cli.js",
        "--transport", "stdio"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

📖 See the Configuration Wiki for more configuration options.

If MySQL is installed directly on your computer (via installer, Homebrew, etc.):

"--mysql", "mysql://user:[email protected]:3306/database"

Add both containers to the same Docker network, then use the container name:

# Create network and run MySQL
docker network create mynet
docker run -d --name mysql-db --network mynet -e MYSQL_ROOT_PASSWORD=pass mysql:8
# Run MCP server on same network
docker run -i --rm --network mynet writenotenow/mysql-mcp:latest \
  --transport stdio --mysql mysql://root:pass@mysql-db:3306/mysql

Use the remote hostname directly:

"--mysql", "mysql://user:[email protected]:3306/database"

Tip: For remote connections, ensure your MySQL server allows connections from Docker's IP range and that firewalls/security groups permit port 3306.

The --tool-filter argument accepts shortcuts, groups, or tool names — mix and match freely:

Add one of these configurations to your IDE's MCP settings file (e.g., cline_mcp_settings.json, .cursorrules, or equivalent):

Best for: General MySQL database work - CRUD operations, schema management, and monitoring.

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": [
        "/path/to/mysql-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--tool-filter",
        "starter"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Best for: Monitoring InnoDB Cluster, Group Replication status, and cluster topology.

⚠️ Prerequisites:

• InnoDB Cluster must be configured and running with Group Replication enabled
• Connect to a cluster node directly (e.g., localhost:3307) — NOT a standalone MySQL instance
• Use cluster_admin or root user with appropriate privileges
• See MySQL Ecosystem Setup Guide for cluster setup instructions

{
  "mcpServers": {
    "mysql-mcp-cluster": {
      "command": "node",
      "args": [
        "/path/to/mysql-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--tool-filter",
        "cluster"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3307",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "mysql"
      }
    }
  }
}

Best for: MySQL Router, ProxySQL, MySQL Shell, and InnoDB Cluster deployments.

⚠️ Prerequisites:

• InnoDB Cluster with MySQL Router requires the cluster to be running for Router REST API authentication (uses metadata_cache backend)
• Router REST API uses HTTPS with self-signed certificates by default — set MYSQL_ROUTER_INSECURE=true to bypass certificate verification
• See MySQL Ecosystem Setup Guide for detailed instructions

{
  "mcpServers": {
    "mysql-mcp-ecosystem": {
      "command": "node",
      "args": [
        "/path/to/mysql-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--tool-filter",
        "ecosystem"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3307",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "mysql",
        "MYSQL_ROUTER_URL": "https://localhost:8443",
        "MYSQL_ROUTER_USER": "rest_api",
        "MYSQL_ROUTER_PASSWORD": "router_password",
        "MYSQL_ROUTER_INSECURE": "true",
        "PROXYSQL_HOST": "localhost",
        "PROXYSQL_PORT": "6032",
        "PROXYSQL_USER": "radmin",
        "PROXYSQL_PASSWORD": "radmin",
        "MYSQLSH_PATH": "/usr/local/bin/mysqlsh"
      }
    }
  }
}

Customization Notes:

• Replace /path/to/mysql-mcp/ with your actual installation path
• Update credentials with your actual values
• For Windows: Use forward slashes (e.g., C:/mysql-mcp/dist/cli.js) or escape backslashes
• For Windows MySQL Shell: "MYSQLSH_PATH": "C:\\Program Files\\MySQL\\MySQL Shell 9.5\\bin\\mysqlsh.exe"
• Router Authentication: Router REST API authenticates against the InnoDB Cluster metadata. The cluster must be running for authentication to work.
• Cluster Resource: The mysql://cluster resource is only available when connected to an InnoDB Cluster node

Legacy Syntax (still supported): If you start with a negative filter (e.g., -ecosystem), it assumes you want to start with all tools enabled and then subtract.

📖 See the Tool Filtering Wiki for advanced examples.

For debugging or manual reference, see the source: src/constants/ServerInstructions.ts

This server includes 19 intelligent prompts for guided workflows:

This server exposes 18 resources for database observability:

For specialized setups, see these Wiki pages:

Tip: Lower METADATA_CACHE_TTL_MS for development (e.g., 5000), or increase it for production with stable schemas (e.g., 300000 = 5 min).

📖 See the OAuth Wiki for Keycloak setup and detailed configuration.

Use MCP Inspector to visually test and debug mysql-mcp:

# Build the server first
npm run build

# Launch Inspector with mysql-mcp
npx @modelcontextprotocol/inspector node dist/cli.js \
  --transport stdio \
  --mysql mysql://user:password@localhost:3306/database

Open http://localhost:6274 to browse all 191 tools, 18 resources, and 19 prompts interactively.

CLI mode for scripting:

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/cli.js \
  --transport stdio --mysql mysql://... \
  --method tools/list

# Call a specific tool  
npx @modelcontextprotocol/inspector --cli node dist/cli.js \
  --transport stdio --mysql mysql://... \
  --method tools/call --tool-name mysql_list_tables

📖 See the MCP Inspector Wiki for detailed usage.

The project maintains high test coverage (~97%) using Vitest.

# Run tests
npm test

# Run coverage report
npm run test:coverage

Test Infrastructure:

• Centralized mock factories in src/__tests__/mocks/
• All 101 test files use shared mocks for consistency
• Tests run without database connection (fully mocked)
• ~53 second total runtime

Test Coverage:

Contributions are welcome! Please read our Contributing Guidelines before submitting a pull request.

For security concerns, please see our Security Policy.

⚠️ Never commit credentials - Store secrets in .env (gitignored)

This project is licensed under the MIT License - see the LICENSE file for details.

Please read our Code of Conduct before participating in this project.