mysql-mcp

Last updated December 16, 2025 - Production/Stable v2.0.0

📚 Full Documentation (Wiki) • Changelog • Security

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. Built for developers who demand enterprise-grade features without sacrificing ease of use.

🎯 What Sets Us Apart

Feature	Description
191 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.0 + Access Control	Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (`read`, `write`, `admin`, `full`, `db:`, `table::*`), and Keycloak integration
Smart Tool Filtering	24 tool groups + 7 meta-groups 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
Production-Ready Security	SQL injection protection, parameterized queries, input validation, and audit capabilities
Strict TypeScript	100% type-safe codebase with 1500+ tests and 97% coverage
MCP 2025-11-25 Compliant	Full protocol support with tool safety hints, resource priorities, and progress notifications

🚀 Quick Start

Prerequisites

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

💡 Jupyter Notebook: Check out our Python Quickstart Notebook for an interactive guide using the Python SDK.

Installation

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

Docker

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

⚡ 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.0 authentication for enterprise security
Allowing multiple AI clients to share one database connection

OAuth 2.0 Authentication

For enterprise deployments, mysql-mcp supports OAuth 2.0 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 --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: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.0 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"
      }
    }
  }
}

📖 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 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

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 191 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend starter (38 tools) as a starting point.

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`	38	Use a predefined bundle
Groups only	`core,json,transactions`	32	Combine individual groups
Shortcut + Group	`starter,spatial`	50	Extend a shortcut
Shortcut - Tool	`starter,-mysql_drop_table`	37	Remove specific tools

Shortcuts (Predefined Bundles)

Shortcut	Tools	Use Case	What's Included
`starter`	38	🌟 Recommended	Core, JSON, trans, text
`essential`	15	Minimal footprint	Core, trans
`dev-power`	45	Power Developer	Core, schema, perf, stats, fulltext, trans
`ai-data`	44	AI Data Analyst	Core, JSON, docstore, text, fulltext
`ai-spatial`	43	AI Spatial Analyst	Core, spatial, stats, perf, trans
`dba-monitor`	35	DBA Monitoring	Core, monitor, perf, sysschema, opt
`dba-manage`	33	DBA Management	Core, admin, backup, repl, parts, events
`dba-secure`	42	DBA Security	Core, security, roles, cluster, trans
`base-core`	48	Base Ops	Core, JSON, trans, text, schema
`base-advanced`	39	Advanced Features	DocStore, spatial, stats, fulltext, events
`ecosystem`	31	External Tools	Router, ProxySQL, Shell

Tool Groups (24 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`	4	Natural language 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
`router`	9	MySQL Router REST API
`proxysql`	12	ProxySQL management
`shell`	10	MySQL Shell utilities
`schema`	10	Views, procedures, triggers, constraints
`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
`cluster`	10	Group Replication, InnoDB Cluster
`roles`	8	MySQL 8.0 role management
`docstore`	9	Document Store collections

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 (38 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: Ecosystem (31 Tools + InnoDB Cluster Resource)

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

⚠️ Prerequisites: Requires MySQL Router, ProxySQL, and MySQL Shell to be installed and configured. 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": "admin",
        "PROXYSQL_PASSWORD": "admin_password",
        "MYSQLSH_PATH": "/usr/local/bin/mysqlsh"
      }
    }
  }
}

Customization Notes:

Replace /path/to/mysql-mcp/ with your actual installation path
Update credentials (your_username, your_password, etc.) with your MySQL credentials
For Windows: Use forward slashes in paths (e.g., C:/mysql-mcp/dist/cli.js) or escape backslashes (C:\\mysql-mcp\\dist\\cli.js)
Cluster Resource: The mysql://cluster resource is only available with ecosystem filter when connected to an InnoDB Cluster node (port 3307 in example). It returns {"groupReplicationEnabled": false} for standard MySQL instances.

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

JSON Tools (`mysql_json_*`)

Strict Quoting: When passing string values to JSON tools (like mysql_json_set or mysql_json_insert), you must quote the string if you intend to store it as a JSON string.
- ❌ Incorrect: value: "green" (interpreted as invalid JSON)
- ✅ Correct: value: "\"green\"" (stored as string "green")
- ✅ Correct: value: 42 (stored as number)
- ✅ Correct: value: {"key": "val"} (stored as object)
Validation: Creating or updating JSON values enforces strict JSON validity checks to prevent silent failures.

Transactions & Safety (`mysql_transaction_*`)

Interactive Transactions: You can perform multiple queries in a single transaction by passing the transactionId returned by mysql_transaction_begin to subsequent mysql_read_query or mysql_write_query calls.
Atomic Operations: Always use transactions for multi-step changes.
1. Call mysql_transaction_begin → get transactionId
2. Perform updates with transactionId
3. If successful, mysql_transaction_commit
4. If error, mysql_transaction_rollback

Document Store (`mysql_doc_*`)

Filters: The filter parameter accepts a MySQL JSON Path string (e.g., $.address.zip), checking for existence. It is not a full conditional expression (e.g., $.type == "A" is invalid).
To filter by value, use mysql_doc_find to retrieve candidates and filter in your application, or use mysql_read_query for complex JSON path conditions.

Fulltext Search (`mysql_fulltext_boolean`)

Operators: Uses standard MySQL boolean operators:
- +word: Mandatory (AND)
- -word: Prohibited (NOT)
- word*: Wildcard (at end of word)
- > <: Relevance weighting

DDL Statements (`mysql_write_query`)

DDL Support: mysql_write_query automatically handles DDL statements (like CREATE TABLE, CREATE USER) that are not supported by the prepared statement protocol. It detects the error and falls back to the text protocol, ensuring seamless execution.

Security & Role Management

Role Permissions: Role management tools (mysql_role_create, mysql_role_grant, etc.) require a user with appropriate privileges.
Schema Qualification: mysql_role_grant supports db.table syntax (e.g., GRANT SELECT ON my_schema.my_table) and correctly handles wildcards.
SSL Status: Server certificate verification status (serverCertVerification) is no longer retrievable via standard variables in MySQL 8.0.34+ and will report as false by default.

Group Replication & InnoDB Cluster

Plugin Requirement: Group Replication tools (mysql_gr_*) check for the group_replication plugin status. If the plugin is not ACTIVE, these tools return a "not active" message instead of failing with SQL errors, allowing safe probing of cluster status.
Cluster Resource (mysql://cluster): This resource provides InnoDB Cluster status including all member nodes. It requires connecting to a cluster node (e.g., port 3307) with a user that has access to performance_schema.replication_group_members. For non-cluster deployments, it will return {"groupReplicationEnabled": false}.

🤖 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

CLI Options

Option	Environment Variable	Description
`--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 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.

Unit Testing

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 98 test files use shared mocks for consistency
Tests run without database connection (fully mocked)
~43 second total runtime

Test Coverage:

Component	Coverage	Notes
Global	97%+	Statement coverage
MySQLAdapter	93%+	Adapter logic covered
Branch Coverage	~85%	High branch coverage
Tools (All)	98%+	1478 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.

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.github		.github
examples		examples
releases		releases
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DOCKER_README.md		DOCKER_README.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
VERSION		VERSION
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

neverinfamous/mysql-mcp

Folders and files

Latest commit

History

Repository files navigation

mysql-mcp

The Most Comprehensive MySQL MCP Server Available

🎯 What Sets Us Apart

🚀 Quick Start

Prerequisites

Installation

Docker

⚡ MCP Client Configuration

HTTP/SSE Server Usage (Advanced)

OAuth 2.0 Authentication

Quick Setup

Cursor IDE / Claude Desktop

Using Environment Variables (Recommended)

🔗 Database Connection Scenarios

MySQL on Host Machine

MySQL in Another Docker Container

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

🛠️ Tool Filtering

What Can You Filter?

Shortcuts (Predefined Bundles)

Tool Groups (24 Available)

Quick Start: Recommended IDE Configuration

Option 1: Starter (38 Essential Tools)

Option 2: Ecosystem (31 Tools + InnoDB Cluster Resource)

Syntax Reference

💡 Usage Instructions

JSON Tools (mysql_json_*)

Transactions & Safety (mysql_transaction_*)

Document Store (mysql_doc_*)

Fulltext Search (mysql_fulltext_boolean)

DDL Statements (mysql_write_query)

Security & Role Management

Group Replication & InnoDB Cluster

🤖 AI-Powered Prompts

📊 Resources

🔧 Advanced Configuration

CLI Options

Scopes

Development

MCP Inspector

Unit Testing

Contributing

Security

License

Code of Conduct

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Uh oh!

Contributors 2

Uh oh!

Languages

JSON Tools (`mysql_json_*`)

Transactions & Safety (`mysql_transaction_*`)

Document Store (`mysql_doc_*`)

Fulltext Search (`mysql_fulltext_boolean`)

DDL Statements (`mysql_write_query`)