mysql-mcp

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

💎 Value Proposition

MySQL MCP is a production-ready integration engineered for AI agents. It minimizes LLM token consumption by up to 90% via sandboxed Code Mode. It scales reliably through built-in connection pooling. It secures database access using strict OAuth 2.1 validation.

🎯 Core Benefits

| Feature | Description | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Specialized Tools | Access 200+ specialized tools. Manage core CRUD, JSON, spatial data, document stores, and clusters. | | 23 Resources | Monitor schema, performance metrics, process lists, replication status, and InnoDB diagnostics in real-time. | | 19 AI-Powered Prompts | Execute guided workflows for query building, schema design, performance tuning, and infrastructure setup. | | Code Mode | Execute operations locally inside a V8 isolate. Reduce LLM token overhead by 70-90%. | | Token-Optimized Payloads | Maximize token efficiency. Use optional flags to reduce response size for large payloads. | | OAuth 2.1 Security | Enforce granular access control with RFC compliance, strict scopes, and Keycloak integration. | | Smart Tool Filtering | Use 28 tool groups and 16 shortcuts to stay within IDE tool limits. | | Dual HTTP Transport | Support modern streamable HTTP and legacy SSE clients simultaneously with full session management. | | Connection Pooling | Leverage built-in connection pooling for efficient, highly concurrent database access. | | Ecosystem Integrations | Manage MySQL Router, ProxySQL, and MySQL Shell utilities directly from your agent. | | Advanced Encryption | Enforce TLS/SSL connections. Manage data masking, encryption monitoring, and compliance effortlessly. | | Production-Ready Security | Prevent SQL injection with parameterized queries. Rely on strict input validation and audit logging. | | Deterministic Errors | Receive structured responses with actionable suggestions. Eliminate silent failures and raw exceptions. | | Strict TypeScript | Deploy a 100% type-safe codebase backed by over 2100 tests and high coverage. Backed by robust Vitest and Playwright suites. Features zero skipped tests. Guarantees deterministic reliability in production. | | Protocol Compliant | Support MCP 2024-11-05 with tool safety hints, resource priorities, and progress notifications. |

🚀 Deploy in Minutes

Meet Prerequisites

• Node.js 24+
• MySQL 5.7, 8.0+, or 9.x (supported with limitations regarding Shell driver versions) server
• pnpm

Install the Server

NPM / PNPM (Recommended)

pnpm add -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

Note on Namespaces: The Docker image uses the writenotenow namespace. The GitHub repo uses neverinfamous.

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

From Source

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

⚡ Maximize Efficiency with Code Mode

Code Mode (mysql_execute_code) reduces token usage by 70-90%. It is included by default.

Code executes in a C++ V8 isolate sandbox. The server uses a physically separate V8 isolate via isolated-vm. The server enforces strict heap limits and synchronous termination. The server maps all mysql.* API calls through the boundary using native wrappers. This includes multiple layers of defense-in-depth and fleet-standard restrictions:

Enforce Engine-Level Restrictions

• ✅ Strict V8 Isolate Boundary — executes within a physically separate V8 isolate. It ensures native objects and prototypes cannot cross the boundary.
• ✅ Memory & CPU Constraints — enforced at the C++ level. This includes synchronous timeouts and strict heap limits.
• ✅ API Bindings via Reference — all MySQL API methods are securely injected into the isolate using ivm.Reference wrappers.

Validate Code Statically

• ✅ 29 blocked patterns — regex rules block require(), import(), eval(), process, and __proto__. They also block filesystem/network access and system commands.
• ✅ Unicode & Comment Sanitization — performs NFKC normalization and strips all comments before pattern validation to prevent regex evasion.
• ✅ 50KB code input limit — prevents payload-based resource exhaustion.

Protect the Runtime

• ✅ RPC Quotas — strict cap of 100 API calls per execution to prevent unbounded loops.
• ✅ Execution timeout — Enforces a 30s hard limit. It prevents resource exhaustion.
• ✅ Egress boundary enforcement — streaming JSON.stringify serialization aborts mid-flight when exceeding size caps (default 100KB).
• ✅ Rate limiting — 60 executions per minute per client. Distributed across deployments via Redis if REDIS_URL is provided, with graceful in-memory fallback.
• ✅ Readonly enforcement — when readonly: true, write methods return structured errors instead of executing.
• ✅ Audit logging — Logs every execution with UUID, metrics, and redacted code preview.
• ✅ Admin scope — Code Mode requires admin scope when OAuth is enabled.
• ✅ Full API access — Exposes all 28 tool groups via the mysql.* namespace.

⚡ Run Only Code Mode

Run with only Code Mode enabled. A single tool provides full capability access:

{
  "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",
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

This exposes just mysql_execute_code. Agents write JavaScript against the typed SDK. They compose queries and chain operations across 28 groups. They return exactly the needed data in one execution. This mirrors the Code Mode pattern. It ensures fixed token costs.

[!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.

🌐 Connect Remotely via HTTP/SSE

Use the HTTP transport for remote access:

npx -y @neverinfamous/mysql-mcp \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --mysql "mysql://user:pass@localhost:3306/db"

Docker:

docker run --rm -p 3000:3000 \
  writenotenow/mysql-mcp:latest \
  --transport http --server-host 0.0.0.0 --port 3000 --mysql "mysql://user:[email protected]:3306/db"

The server supports two MCP transport protocols simultaneously. Both modern and legacy clients can connect:

Use Streamable HTTP (Recommended)

Modern protocol (MCP 2024-11-05) — single endpoint, session-based:

| Method | Endpoint | Purpose | | -------- | -------- | ------------------------------------------------ | | POST | /mcp | JSON-RPC requests (initialize, tools/list, etc.) | | GET | /mcp | SSE stream for server notifications | | DELETE | /mcp | Session termination |

Rate Limit: HTTP transport is limited to 100 requests per minute per IP. Distributed across deployments via Redis if REDIS_URL is provided, with graceful in-memory fallback.

Sessions are managed via the Mcp-Session-Id header.

Run Statelessly

Use stateless deployments where sessions are not needed:

node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --stateless --mysql "mysql://..."

In stateless mode: GET /mcp returns 405, DELETE /mcp returns 204, /sse and /messages return 404. Each POST /mcp creates a fresh transport.

Connect via Legacy SSE (Backward Compatibility)

Legacy protocol (MCP 2024-11-05) — for clients like Python mcp.client.sse:

| Method | Endpoint | Purpose | | ------ | -------------------------- | ------------------------------------------------------------- | | GET | /sse | Opens SSE stream, returns /messages?sessionId=<id> endpoint | | POST | /messages?sessionId=<id> | Send JSON-RPC messages to the session |

Access Utility Endpoints

| Method | Endpoint | Purpose | | ------ | --------- | ---------------------------------------------------------------------- | | GET | /health | Health check (bypasses rate limiting, always available for monitoring) |

🔐 Secure Access with Authentication

mysql-mcp supports two authentication mechanisms for HTTP transport:

Authenticate Fast with Bearer Tokens (--auth-token)

Use lightweight authentication for development:

node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --auth-token my-secret --mysql "mysql://..."

# Or via environment variable
export MCP_AUTH_TOKEN=my-secret
node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --mysql "mysql://..."

Clients must include Authorization: Bearer my-secret on all requests. /health and / are exempt. Unauthenticated requests receive 401 with WWW-Authenticate: Bearer headers per RFC 6750.

Enforce Enterprise Security with OAuth 2.1

Use full OAuth 2.1 for production deployments:

node dist/cli.js \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --mysql "mysql://user:pass@localhost:3306/db" \
  --oauth-enabled \
  --oauth-issuer http://localhost:8080/realms/mysql-mcp \
  --oauth-audience mysql-mcp-client

Additional flags: --oauth-jwks-uri <url> (auto-discovered if omitted), --oauth-clock-tolerance <seconds> (default: 60).

OAuth Scopes

Access control is managed through OAuth scopes:

| Scope | Access Level | | ------------------------ | ----------------------------------- | | read | Read-only queries (SELECT, EXPLAIN) | | write | Read + write operations | | admin | Full administrative access | | full | Grants all access | | db:{name} | Access to specific database | | schema:{name} | Access to specific schema | | table:{schema}:{table} | Access to specific table |

RFC Compliance & Enterprise Security

This implementation follows full OAuth 2.1 for production multi-tenant deployments:

• ✅ RFC 9728 Protected Resource Metadata (/.well-known/oauth-protected-resource)
• ✅ RFC 8414 Authorization Server Discovery with caching
• ✅ RFC 7591 OAuth 2.1 Dynamic Client Registration
• ✅ JWT validation with JWKS support (TTL: 1 hour, configurable)
• ✅ MySQL-specific scopes: read, write, admin, full, db:{name}, schema:{name}, table:{schema}:{table}
• ✅ Per-tool scope enforcement via AsyncLocalStorage context threading

Note for Keycloak users: Add an Audience mapper to your client. This includes the correct aud claim. (Client → Client scopes → dedicated scope → Add mapper → Audience)

[!NOTE] Per-tool scope enforcement: Scopes are enforced at the tool level. Each tool group requires a specific scope. When OAuth is enabled, every tool invocation checks the calling token's scopes before execution. When OAuth is not configured, scope checks are skipped entirely.

[!WARNING] HTTP without authentication: When using --transport http without enabling OAuth or --auth-token, all clients have full unrestricted access. Always enable authentication for production HTTP deployments. See SECURITY.md for details.

Cursor IDE / Claude Desktop

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--mysql",
        "mysql://user:password@localhost:3306/database"
      ]
    }
  }
}

Using Environment Variables (Recommended)

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": ["-y", "@neverinfamous/mysql-mcp", "--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.

🔗 Connect to Any Database

| Scenario | Host to Use | Example Connection String | | ------------------------- | ------------------------- | ------------------------------------------------ | | MySQL on host machine | host.docker.internal | mysql://user:[email protected]:3306/db | | MySQL in Docker | host.docker.internal (Local) or mysql (Docker Compose) | mysql://user:[email protected]:3306/db | | Remote/Cloud MySQL | Hostname or IP | mysql://user:[email protected]:3306/db |

MySQL on Host Machine

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

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

MySQL in Another Docker Container

For local Docker setups, standardize on host.docker.internal. If you are using Docker Compose, you can use the service name mysql (or your specific container name) for docker-compose networking:

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:[email protected]: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.

🛠️ Optimize Limits with Tool Filtering

[!IMPORTANT] AI IDEs like Cursor have tool limits (typically 40-50 tools). With 200+ tools available, you MUST use tool filtering. This keeps you within your IDE's limits. All shortcuts and tool groups include Code Mode by default. To exclude it, add -codemode to your filter: --tool-filter core,json,-codemode

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 | 43 | Use a predefined bundle | | Groups only | core,json,transactions | 36 | Combine individual groups | | Shortcut + Group | starter,spatial | 55 | Extend a shortcut | | Shortcut - Tool | starter,-mysql_drop_table | 42 | Remove specific tools |

Shortcuts (Predefined Bundles)

| Shortcut | Tools | Use Case | What's Included | | --------------- | ------ | ------------------ | ------------------------------------------------------------------ | | starter | 43 | Standard Package | core, json, transactions, text, codemode | | essential | 20 | Minimal footprint | core, transactions, codemode | | dev-power | 47 | Power Developer | core, schema, performance, fulltext, transactions, codemode | | dev-analytics | 44 | Developer Analytics | core, stats, performance, codemode | | ai-data-nosql | 39 | AI Data NoSQL | core, json, docstore, codemode | | ai-search | 35 | AI Search | core, text, fulltext, vector, codemode | | ai-spatial | 32 | AI Spatial Analyst | core, spatial, transactions, codemode | | ai-vector | 29 | AI Vector Analyst | core, vector, fulltext, codemode | | dba-monitor | 43 | DBA Monitoring | core, monitoring, performance, sysschema, optimization, codemode | | dba-manage | 44 | DBA Management | core, admin, backup, replication, partitioning, events, codemode | | dba-secure | 37 | DBA Security | core, security, roles, transactions, codemode | | dba-schema | 36 | DBA Schema | core, schema, introspection, migration, codemode | | base-relational | 37 | Base Relational | core, transactions, text, schema, codemode | | base-analytics | 27 | Base Analytics | stats, events, codemode | | base-nosql | 33 | Base NoSQL | docstore, spatial, vector, codemode | | ecosystem | 41 | External Tools | cluster, proxysql, router, shell, codemode |

Tool Groups (28 Available)

Note: Tool counts below do NOT include Code Mode (mysql_execute_code), which is automatically added to all groups.

| Group | Tools | Description | | --------------- | ----- | ------------------------------------------------------- | | codemode | 1 | Code Mode (sandboxed code execution) 🌟 Recommended | | core | 12 | 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 | 11 | EXPLAIN, query analysis, anomaly detection | | optimization | 4 | Index hints, database-wide audits, EXPLAIN recommendations | | admin | 9 | OPTIMIZE, ANALYZE, CHECK, insights | | monitoring | 7 | PROCESSLIST, status variables | | backup | 7 | Export, import, mysqldump, audit backups | | replication | 5 | Master/slave, binlog | | partitioning | 4 | Partition management | | schema | 11 | Views, procedures, triggers, constraints | | introspection | 6 | Dependency graphs, cascade simulation, snapshots | | migration | 6 | Schema versioning, apply, rollback, history | | shell | 10 | MySQL Shell utilities | | events | 6 | Event Scheduler management | | sysschema | 8 | sys schema diagnostics | | stats | 20 | Statistical analysis, window functions, sampling | | 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 | | vector | 11 | Vector embeddings, KNN search, hybrid search (MySQL 9.0+)|

Quick Start: Recommended IDE Configuration

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

Option 1: Code Mode (Maximum Token Savings, 🌟 Recommended)

Best for: General MySQL database work with an AI agent. Exposes a single tool (mysql_execute_code) that provides access to its full toolset via a JavaScript sandbox.

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "codemode"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "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": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--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 requires a running cluster. This enables Router REST API authentication.
• Router REST API uses self-signed HTTPS certificates. Set MYSQL_ROUTER_INSECURE=true to bypass 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": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--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 enables all tools first. It then subtracts the specified tools.

Syntax Reference

| Prefix | Target | Example | Effect | | -------- | -------- | ------------------- | --------------------------------------------- | | (none) | Shortcut | starter | Whitelist Mode: Enable ONLY this shortcut | | (none) | Group | core | Whitelist Mode: Enable ONLY this group | | (none) | Tool | mysql_read_query | Whitelist Mode: Enable ONLY this tool | | + | 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 |

Custom Tool Selection

You can list individual tool names (without + prefix) to create a fully custom whitelist — only the tools you specify will be enabled:

The easiest way to filter is using whitelist mode. Simply specify the shortcut you want. Everything else is automatically disabled.

Architectural Rule: Tool filtering allows skipping the --mysql connection. Do this if only ecosystem tools (router, proxysql, shell) are used.

# Enable exactly 3 tools (whitelist mode)
--tool-filter "mysql_read_query,mysql_write_query,mysql_list_tables"

# Mix tools from different groups
--tool-filter "mysql_read_query,mysql_explain,mysql_json_extract"

# Combine with a shortcut or group
--tool-filter "starter,+mysql_spatial_distance,+mysql_json_diff"

This is useful for scripted or automated clients that need a minimal, precise set of capabilities.

📖 See the Tool Filtering Wiki for advanced examples.

🤖 Automate Workflows with AI 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 |

📊 Monitor Health with Resources

This server exposes 23 resources for database observability and telemetry:

| Resource | Description | | ----------------------- | ------------------------------------------- | | mysql://schema | Full database schema | | mysql://tables | Table listing with metadata | | mysql://table/{name} | Specific Table Schema | | 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 | | mysql://insights | Business insights memo from mysql_append_insight | | mysql://audit-log | Forensic audit trail and pre-mutation snapshot stats | | mysql://metrics | In-memory streaming telemetry (p50/p95/p99 latency) | | mysql://help | Critical gotchas, parameter aliases, and API reference |

🔧 Customize with Advanced Configuration

Tip: Configure the server using native JSON or YAML files via the --config <path> flag. Precedence follows: CLI Flags > Environment Variables > Config File > Defaults. See the server-config-example.json template at the root of the project for setup details.

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 |

⚡ Boost Speed with Performance Tuning

The server caches schema metadata 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, warn, 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. They also support 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 the code map for per-tool details.

CLI Options

| Option | Environment Variable | Description | | ------------------------- | ----------------------- | --------------------------------------------------- | | --config, -c | — | Configuration file path (.yaml or .json) | | --dump-config | — | Dump current configuration to stdout and exit |

| --transport, -t | — | Transport type: stdio, http, sse (default: stdio) | | --port, -p | MYSQLMCP_PORT | HTTP port for http/sse transports | | --server-host | MCP_HOST | Host to bind HTTP transport to (default: localhost) | | --mysql, -m | — | MySQL connection string | | --mysql-host | MYSQL_HOST | MySQL host | | --mysql-port | MYSQL_PORT | MySQL port | | --mysql-user | MYSQL_USER | MySQL username | | --mysql-password | MYSQL_PASSWORD | MySQL password | | --mysql-database | MYSQL_DATABASE | MySQL database name | | --pool-size | MYSQL_POOL_SIZE | Connection pool size (default: 10) | | --pool-min | MYSQL_POOL_MIN | Minimum connections in pool (default: 0) | | --pool-timeout | — | Connection acquire timeout in ms (default: 30000) | | --pool-queue-limit | — | Queue limit for waiting requests (default: 0) | | --tool-filter, -f | TOOL_FILTER | Tool filter string | | --name | — | Server name | | --auth-token | MCP_AUTH_TOKEN | Simple bearer token for HTTP authentication | | --stateless | — | Enable stateless HTTP mode (no sessions, no SSE) | | --trust-proxy | TRUST_PROXY | Trust X-Forwarded-For for client IP | | --enable-hsts | MCP_ENABLE_HSTS | Enable HTTP Strict Transport Security | | --metrics-export | MCP_METRICS_EXPORT | Enable prometheus metrics endpoint | | --log-level | LOG_LEVEL | Log level: debug, info, warn, error | | --allowed-io-roots | ALLOWED_IO_ROOTS | JSON array or comma list of allowed paths for HTTP/SSE and shell tools | | --audit-log | AUDIT_LOG_PATH | Path to the audit log file | | --audit-backup | — | Enable pre-mutation snapshots | | --audit-reads | — | Include read-scope tool calls in the audit log | | --audit-redact | — | Redact sensitive arguments in the audit log | | --audit-log-max-size | — | Max file size before rotation (bytes) | | --audit-backup-data | — | Include sample data in pre-mutation snapshots | | --audit-backup-max-size | — | Max table size in bytes for data capture | | --oauth-enabled, -o | OAUTH_ENABLED | Enable OAuth 2.1 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 | | — | MYSQL_ROUTER_URL | MySQL Router URL | | — | MYSQL_ROUTER_USER | MySQL Router user | | — | MYSQL_ROUTER_PASSWORD | MySQL Router password | | — | MYSQL_ROUTER_INSECURE | Bypass Router TLS verification | | — | PROXYSQL_HOST | ProxySQL host | | — | PROXYSQL_PORT | ProxySQL port | | — | PROXYSQL_USER | ProxySQL user | | — | PROXYSQL_PASSWORD | ProxySQL password | | — | MYSQLSH_PATH | Path to MySQL Shell executable | | — | MYSQL_XPORT | MySQL X Protocol port (default 33060) | | — | CODEMODE_ISOLATION | Code mode isolation level | | — | CODE_MODE_MAX_RESULT_SIZE | Max Code Mode result payload in bytes | | — | METADATA_CACHE_TTL_MS | Cache TTL for schema metadata | | — | REDIS_URL | Redis connection URL (used for rate limiting) | | — | MCP_REQUEST_TIMEOUT | Global request timeout in ms (default 30000) | | — | MCP_HEADERS_TIMEOUT | Global headers timeout in ms (default 5000) |

Priority: When both --auth-token and --oauth-enabled are set, OAuth 2.1 takes precedence. If neither is configured, the server warns and runs without authentication.

Scopes

| Scope | Access Level | | ------------------------ | ----------------------------------- | | read | Read-only queries (SELECT, EXPLAIN) | | write | Read + write operations | | admin | Full administrative access | | full | Grants all access | | db:{name} | Access to specific database | | schema:{name} | Access to specific schema | | table:{schema}:{table} | Access to specific table |

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

💻 Extend and Contribute

See From Source above for setup. After cloning:

pnpm run check  # Run lint, typecheck, unit tests, and E2E tests

MCP Inspector

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

Build the server first:

pnpm 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:5173 to browse all 241 tools, 23 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.

pnpm test

Run coverage report:

pnpm 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)

Benchmarking

The project includes a performance benchmarking suite to track the efficiency of critical paths like Code Mode sandbox initialization, tool filtering, and URI routing.

pnpm run bench

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.