mysql-mcp

Last Updated February 26, 2026

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

The Most Comprehensive MySQL MCP Server Available

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, deterministic error handling, and process-isolated sandboxed code execution. Built for developers who demand enterprise-grade features without sacrificing ease of use.

🎯 What Sets Us Apart

Feature	Description
192 Specialized Tools	The largest MySQL tool collection for MCP — from core CRUD and native JSON functions (MySQL 5.7+) to advanced spatial/GIS, document store, and cluster management
18 Observability Resources	Real-time schema, performance metrics, process lists, status variables, replication status, and InnoDB diagnostics
19 AI-Powered Prompts	Guided workflows for query building, schema design, performance tuning, and infrastructure setup
OAuth 2.1 + Access Control	Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (read, write, admin, full, db:*, table:*:*), and Keycloak integration
Smart Tool Filtering	25 tool groups + 11 shortcuts let you stay within IDE limits while exposing exactly what you need
HTTP Streaming Transport	SSE-based streaming with /sse, /messages, and /health endpoints for remote deployments
High-Performance Pooling	Built-in connection pooling for efficient, concurrent database access
Ecosystem Integrations	First-class support for MySQL Router, ProxySQL, and MySQL Shell utilities
Advanced Encryption	Full TLS/SSL support for secure connections, plus tools for managing data masking, encryption monitoring, and compliance
Deterministic Error Handling	Every tool returns structured {success, error} responses — no raw exceptions, no silent failures, no misleading messages. Agents get actionable context instead of cryptic MySQL error codes
Production-Ready Security	SQL injection protection, parameterized queries, input validation, and audit capabilities
Worker Sandbox Isolation	Code Mode executes in a separate V8 isolate via worker_threads with a MessagePort RPC bridge, enforced memory limits, readonly mode, and hard timeouts
Strict TypeScript	100% type-safe codebase with 2169 tests and 90% coverage
MCP 2025-11-25 Compliant	Full protocol support with tool safety hints, resource priorities, and progress notifications

---

🚀 Quick Start

Prerequisites

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

Installation

NPM (Recommended)

npm install -g @neverinfamous/mysql-mcp

Run the server:

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

docker run -i --rm writenotenow/mysql-mcp:latest \
  --transport stdio \
  --mysql mysql://user:password@host.docker.internal:3306/database

From Source

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

---

Code Mode: Maximum Efficiency

Code Mode (mysql_execute_code) dramatically reduces token usage (70–90%) and is included by default in all presets.

Code executes in a worker-thread sandbox — a separate V8 isolate with its own memory space. All mysql.* API calls are forwarded to the main thread via a MessagePort-based RPC bridge, where the actual database operations execute. This provides:

• Process-level isolation — user code runs in a separate V8 instance with enforced heap limits
• Readonly enforcement — when readonly: true, write methods return structured errors instead of executing
• Hard timeouts — worker termination if execution exceeds the configured limit
• Full API access — all 24 tool groups are available via mysql.* (e.g., mysql.core.readQuery(), mysql.json.extract())

Set CODEMODE_ISOLATION=vm to fall back to the in-process vm module sandbox if needed.

⚡ Code Mode Only (Maximum Token Savings)

If you control your own setup, you can run with only Code Mode enabled — a single tool that provides access to all 192 tools' worth of capability through the mysql.* API:

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

This exposes just mysql_execute_code. The agent writes JavaScript against the typed mysql.* SDK — composing queries, chaining operations across all 24 tool groups, and returning exactly the data it needs — in one execution. This mirrors the Code Mode pattern pioneered by Cloudflare for their entire API: fixed token cost regardless of how many capabilities exist.

[!TIP] Maximize Token Savings: Instruct your AI agent to prefer Code Mode over individual tool calls:

"When using mysql-mcp, prefer mysql_execute_code (Code Mode) for multi-step database operations to minimize token usage."

For maximum savings, use --tool-filter codemode to run with Code Mode as your only tool. See the Code Mode wiki for full API documentation.

[!NOTE] AntiGravity Users: Server instructions are automatically sent to MCP clients during initialization. However, AntiGravity does not currently support MCP server instructions. For optimal Code Mode usage in AntiGravity, manually provide the contents of src/constants/ServerInstructions.ts to the agent in your prompt or user rules.

---

⚡ MCP Client Configuration

HTTP/SSE Server Usage (Advanced)

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

OAuth 2.1 Authentication

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

Quick Setup

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 --server-host 0.0.0.0 --mysql mysql://user:password@localhost:3306/database

Docker (expose port 3000):

docker run -p 3000:3000 writenotenow/mysql-mcp \
  --transport http \
  --port 3000 \
  --server-host 0.0.0.0 \
  --mysql mysql://user:password@host.docker.internal: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.

Cursor IDE / Claude Desktop

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

Using Environment Variables (Recommended)

{
  "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",
        "MYSQL_XPORT": "33060"
      }
    }
  }
}

> **Note:** `MYSQL_XPORT` (X Protocol port) defaults to `33060` if omitted. Only needed for `mysqlsh_import_json` and `docstore` tools. Set to your MySQL Router X Protocol port (e.g., `6448`) when using InnoDB Cluster.

📖 See the Configuration Wiki for more configuration options.

---

🔗 Database Connection Scenarios

Scenario	Host to Use	Example Connection String
MySQL on host machine	host.docker.internal	mysql://user:pass@host.docker.internal:3306/db
MySQL in Docker	Container name or network	mysql://user:pass@mysql-container:3306/db
Remote/Cloud MySQL	Hostname or IP	mysql://user:pass@db.example.com:3306/db

MySQL on Host Machine

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

"--mysql", "mysql://user:password@host.docker.internal:3306/database"

MySQL in Another Docker Container

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

Create a 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 the same network:

docker run -i --rm --network mynet writenotenow/mysql-mcp:latest \
  --transport stdio --mysql mysql://root:pass@mysql-db:3306/mysql

Remote/Cloud MySQL (RDS, Cloud SQL, etc.)

Use the remote hostname directly:

"--mysql", "mysql://user:password@your-instance.region.rds.amazonaws.com:3306/database"

Provider	Example Hostname
AWS RDS	your-instance.xxxx.us-east-1.rds.amazonaws.com
Google Cloud SQL	project:region:instance (via Cloud SQL Proxy)
Azure MySQL	your-server.mysql.database.azure.com
PlanetScale	aws.connect.psdb.cloud (SSL required)
DigitalOcean	your-cluster-do-user-xxx.db.ondigitalocean.com

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

---

🛠️ Tool Filtering

[!IMPORTANT] AI IDEs like Cursor have tool limits (typically 40-50 tools). With 192 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend starter (39 tools) as a starting point. Code Mode is included in all presets by default for 70-90% token savings on multi-step operations.

What Can You Filter?

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

Filter Pattern	Example	Tools	Description
Shortcut only	starter	39	Use a predefined bundle
Groups only	core,json,transactions	33	Combine individual groups
Shortcut + Group	starter,spatial	51	Extend a shortcut
Shortcut - Tool	starter,-mysql_drop_table	38	Remove specific tools

Shortcuts (Predefined Bundles)

Shortcut	Tools	Use Case	What's Included
starter	39	🌟 Recommended	core, json, transactions, text, codemode
essential	16	Minimal footprint	core, transactions, codemode
dev-power	47	Power Developer	core, schema, performance, stats, fulltext, transactions, codemode
ai-data	46	AI Data Analyst	core, json, docstore, text, fulltext, codemode
ai-spatial	44	AI Spatial Analyst	core, spatial, stats, performance, transactions, codemode
dba-monitor	36	DBA Monitoring	core, monitoring, performance, sysschema, optimization, codemode
dba-manage	34	DBA Management	core, admin, backup, replication, partitioning, events, codemode
dba-secure	33	DBA Security	core, security, roles, transactions, codemode
base-core	49	Base Ops	core, json, transactions, text, schema, codemode
base-advanced	41	Advanced Features	docstore, spatial, stats, fulltext, events, codemode
ecosystem	41	External Tools	cluster, proxysql, router, shell, codemode

Tool Groups (25 Available)

Group	Tools	Description
core	8	Read/write queries, tables, indexes
transactions	7	BEGIN, COMMIT, ROLLBACK, savepoints
json	17	JSON functions, merge, diff, stats
text	6	REGEXP, LIKE, SOUNDEX
fulltext	5	Natural language & boolean search
performance	8	EXPLAIN, query analysis, slow queries
optimization	4	Index hints, recommendations
admin	6	OPTIMIZE, ANALYZE, CHECK
monitoring	7	PROCESSLIST, status variables
backup	4	Export, import, mysqldump
replication	5	Master/slave, binlog
partitioning	4	Partition management
schema	10	Views, procedures, triggers, constraints
shell	10	MySQL Shell utilities
events	6	Event Scheduler management
sysschema	8	sys schema diagnostics
stats	8	Statistical analysis tools
spatial	12	Spatial/GIS operations
security	9	Audit, SSL, encryption, masking
roles	8	MySQL 8.0 role management
docstore	9	Document Store collections
cluster	10	Group Replication, InnoDB Cluster
proxysql	11	ProxySQL management
router	9	MySQL Router REST API
codemode	1	Sandboxed code execution

---

Quick Start: Recommended IDE Configuration

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

Option 1: Starter (39 Essential Tools)

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"
      }
    }
  }
}

Option 2: Cluster (11 Tools for InnoDB Cluster Monitoring)

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"
      }
    }
  }
}

Option 3: Ecosystem (41 Tools for InnoDB Cluster Deployments)

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
• X Protocol: InnoDB Cluster includes the MySQL X Plugin by default. Set MYSQL_XPORT to the Router's X Protocol port (e.g., 6448) for mysqlsh_import_json and docstore tools
• 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_XPORT": "6448",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "testdb",
        "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.

Syntax Reference

Prefix	Target	Example	Effect
(none)	Shortcut	starter	Whitelist Mode: Enable ONLY this shortcut
(none)	Group	core	Whitelist Mode: Enable ONLY this group
+	Group	+spatial	Add tools from this group to current set
-	Group	-admin	Remove tools in this group from current set
+	Tool	+mysql_explain	Add one specific tool
-	Tool	-mysql_drop_table	Remove one specific tool

📖 See the Tool Filtering Wiki for advanced examples.

---

💡 Usage Instructions

[!NOTE] Usage instructions are automatically provided to AI agents via the MCP protocol during server initialization.

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

---

🤖 AI-Powered Prompts

This server includes 19 intelligent prompts for guided workflows:

Prompt	Description
mysql_query_builder	Construct SQL queries with security best practices
mysql_schema_design	Design table schemas with indexes and relationships
mysql_performance_analysis	Analyze slow queries with optimization recommendations
mysql_migration	Generate migration scripts with rollback options
mysql_database_health_check	Comprehensive database health assessment
mysql_backup_strategy	Enterprise backup planning with RTO/RPO
mysql_index_tuning	Index analysis and optimization workflow
mysql_setup_router	MySQL Router configuration guide
mysql_setup_proxysql	ProxySQL configuration guide
mysql_setup_replication	Replication setup guide
mysql_setup_shell	MySQL Shell usage guide
mysql_tool_index	Complete tool index with categories
mysql_quick_query	Quick query execution shortcut
mysql_quick_schema	Quick schema exploration
mysql_setup_events	Event Scheduler setup guide
mysql_sys_schema_guide	sys schema usage and diagnostics
mysql_setup_spatial	Spatial/GIS data setup guide
mysql_setup_cluster	InnoDB Cluster/Group Replication guide
mysql_setup_docstore	Document Store / X DevAPI guide

---

📊 Resources

This server exposes 18 resources for database observability:

Resource	Description
mysql://schema	Full database schema
mysql://tables	Table listing with metadata
mysql://variables	Server configuration variables
mysql://status	Server status metrics
mysql://processlist	Active connections and queries
mysql://pool	Connection pool statistics
mysql://capabilities	Server version, features, tool categories
mysql://health	Comprehensive health status
mysql://performance	Query performance metrics
mysql://indexes	Index usage and statistics
mysql://replication	Replication status and lag
mysql://innodb	InnoDB buffer pool and engine metrics
mysql://events	Event Scheduler status and scheduled events
mysql://sysschema	sys schema diagnostics summary
mysql://locks	InnoDB lock contention detection
mysql://cluster	Group Replication/InnoDB Cluster status
mysql://spatial	Spatial columns and indexes
mysql://docstore	Document Store collections

---

🔧 Advanced Configuration

For specialized setups, see these Wiki pages:

Topic	Description
MySQL Router	Configure Router REST API access for InnoDB Cluster
ProxySQL	Configure ProxySQL admin interface access
MySQL Shell	Configure MySQL Shell for dump/load operations

---

⚡ Performance Tuning

Schema metadata is cached to reduce repeated queries during tool/resource invocations.

Variable	Default	Description
METADATA_CACHE_TTL_MS	30000	Cache TTL for schema metadata (milliseconds)
LOG_LEVEL	info	Log verbosity: debug, info, warning, error

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

Built-in payload optimization: Many tools support optional summary: true for condensed responses and limit parameters to cap result sizes. These are particularly useful for cluster status, monitoring, and sys schema tools where full responses can be large. See ServerInstructions.ts for per-tool details.

---

CLI Options

Option	Environment Variable	Description
--server-host	MCP_HOST	Host to bind HTTP transport to (default: localhost)
--oauth-enabled	OAUTH_ENABLED	Enable OAuth authentication
--oauth-issuer	OAUTH_ISSUER	Authorization server URL
--oauth-audience	OAUTH_AUDIENCE	Expected token audience
--oauth-jwks-uri	OAUTH_JWKS_URI	JWKS URI (auto-discovered)
--oauth-clock-tolerance	OAUTH_CLOCK_TOLERANCE	Clock tolerance in seconds

Scopes

Scope	Access Level
read	Read-only queries
write	Read + write operations
admin	Administrative operations
full	All operations

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

Development

MCP Inspector

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 192 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.

Unit Testing

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

npm test

Run coverage report:

npm run test:coverage

Test Infrastructure:

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

Test Coverage:

Component	Coverage	Notes
Global	90%+	Statement coverage
MySQLAdapter	93%+	Adapter logic covered
Branch Coverage	~75%	High branch coverage
Tools (All)	98%+	2169 tests passing

---

Contributing

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

Security

For security concerns, please see our Security Policy.

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

License

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

Code of Conduct

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