Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
docker run -i --rm docker.io/writenotenow/mysql-mcp:v1.0.0Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
claude mcp add io.github.neverinfamous-mysql-mcp -- docker run -i --rm docker.io/writenotenow/mysql-mcp:v1.0.0รันในเทอร์มินัล
{ "mcpServers": { "io.github.neverinfamous-mysql-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "docker.io/writenotenow/mysql-mcp:v1.0.0" ] } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดIntegrate your AI agents with a production-ready MySQL environment. Deploy MCP v2 stateless architecture via HTTP transport. Optimize token efficiency via Code Mode. Secure your database with OAuth 2.1.
This server includes intelligent prompts for guided workflows:
Note: This is a subset of available prompts. Use
mysql_tool_indexto discover the full list of guided workflows.
This server exposes a comprehensive set of resources for database observability and telemetry:
.node-version for the pinned local development version)pnpm add -g @neverinfamous/mysql-mcp
Run the server:
mysql-mcp --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"
Or use npx without installing:
npx @neverinfamous/mysql-mcp --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"
Note on Namespaces: The Docker image uses the
writenotenownamespace. The GitHub repo usesneverinfamous.
Linux Users: For
host.docker.internalon Linux, run the container with--add-host host.docker.internal:host-gateway.
docker run -i --rm -v ./data:/app/data -v ./logs:/var/log/mysql-mcp writenotenow/mysql-mcp:latest \
--transport stdio \
--allowed-io-roots /app/data \
--mysql "mysql://mcp_user:[email protected]:3306/testdb"
Launch the full observability stack using the included template. This includes Datadog, OpenTelemetry, Prometheus, and Grafana. This spins up the MCP server, MySQL database, Redis, and observability sidecars:
cd examples/basic-mysql-datadog
cp .env.example .env
docker compose up -d
http://localhost:3001 (Dashboard pre-loaded).http://localhost:9090.http://localhost:3000.Datadog Constraints:
pup CLI for authentication.tags.datadoghq.com/env, tags.datadoghq.com/service, tags.datadoghq.com/version) to your containers.stop_grace_period: 30s, mem_limit: 1536m, and OpenMetrics timeouts of 10s.DD_HOSTNAME and native /etc/docker/daemon.json cgroup configurations ("default-cgroupns-mode": "host"). Disable DD_EXTRA_PERFORMANCE_METRICS.inotify tailing issues may occur with Docker/WSL2 log mapping.OpenTelemetry Rules:
gen_ai.* semantics.traceparent and tracestate propagation.Audit Architecture & Exporter Healthcheck:
mcp-audit.jsonl via the --audit-log flag.mcp-audit.jsonl using the AUDIT_LOG_PATH environment variable to compute metrics.--audit-log flag to exporter-audit.jsonl.3000. This prevents port contention.wget --spider -q http://127.0.0.1:3000/metricsgit clone https://github.com/neverinfamous/mysql-mcp.git
cd mysql-mcp
pnpm install
pnpm run build
node dist/cli.js --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"
We provide production-ready Docker Compose templates in the examples/ directory. Use these to spin up test environments quickly. These templates include full Datadog observability out-of-the-box (Metrics, APM, and Logs).
See the README in each directory for quick start instructions.
Code Mode (mysql_execute_code) reduces token usage by consolidating operations in a secure sandbox.
Code executes securely in a C++ V8 isolate sandbox. It enforces strict heap limits and synchronous termination. Native wrappers map all API calls across the boundary. This guarantees defense-in-depth and fleet-standard restrictions:
ivm.Reference wrappers.require(), import(), eval(), Function, process, and __proto__. They also block filesystem/network access and system commands.timeout.JSON.stringify serialization aborts mid-flight when exceeding size caps.admin scope when OAuth is enabled.mysql.* namespace.Run with only Code Mode enabled. A single tool provides full capability access. See Option 1: Code Mode below for the recommended IDE configuration.
This exposes just mysql_execute_code. Agents write JavaScript against the typed SDK. They compose queries and chain operations across tool groups. They return exactly the needed data in one execution. This mirrors standard serverless edge execution patterns. It ensures fixed token costs.
[!TIP] Maximize Token Savings: Instruct your AI agent to prefer Code Mode.
"When using mysql-mcp, prefer
mysql_execute_code(Code Mode) for multi-step operations. This minimizes token usage."For maximum savings, run Code Mode as your only tool using
--tool-filter codemode. See the Code Mode wiki for full API documentation.
When to use HTTP mode: Deploy
mysql-mcpas a standalone server. Multiple clients can connect remotely. Usestdiomode for local development.
Use cases for HTTP mode:
Use the HTTP transport for remote access:
npx -y @neverinfamous/mysql-mcp \
--transport http \
--server-host 0.0.0.0 \
--port 3000 \
--allowed-io-roots /path/to/data \
--mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"
Docker:
docker run --rm -p 3000:3000 \
-v ./data:/app/data \
-v ./logs:/var/log/mysql-mcp \
-e MCP_AUTH_TOKEN=my-secret-token \
writenotenow/mysql-mcp:latest \
--transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /app/data --mysql "mysql://mcp_user:[email protected]:3306/testdb"
The server supports Streamable HTTP and Stateless HTTP deployments. Both stateful and stateless clients can connect:
Modern MCP protocol — single endpoint, session-based:
Rate Limit: HTTP transport is rate limited per IP (default 100/min, configurable via
MCP_RATE_LIMIT_MAX). Distribute limits across deployments via Redis using graceful in-memory fallbacks.
The server manages sessions via the Mcp-Session-Id header.
Use stateless deployments where sessions are not needed:
node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --stateless --mysql "mysql://mcp_user:secure_password@..."
In stateless mode: GET /mcp returns 405. DELETE /mcp returns 204. Each POST /mcp instantiates a stateless HTTP transport.
mysql-mcp supports two authentication mechanisms for HTTP transport:
--auth-token)Use lightweight authentication for development:
node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --auth-token my-secret --mysql "mysql://mcp_user:secure_password@..."
# Or via environment variable
export MCP_AUTH_TOKEN=my-secret
node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --mysql "mysql://mcp_user:secure_password@..."
Clients must include Authorization: Bearer my-secret on all requests. /health and / are exempt. Unauthenticated requests receive 401. Responses include WWW-Authenticate: Bearer headers per RFC 6750.
Use full OAuth 2.1 for production deployments:
node dist/cli.js \
--transport http \
--server-host 0.0.0.0 \
--port 3000 \
--allowed-io-roots /path/to/data \
--mysql "mysql://mcp_user:secure_password@localhost:3306/testdb" \
--oauth-enabled \
--oauth-issuer https://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).
Enforce access control using OAuth scopes:
This implementation follows full OAuth 2.1 for production multi-tenant deployments:
/.well-known/oauth-protected-resource)read, write, admin, full, db:{name}, table:{db}:{table}AsyncLocalStorage context threadingNote for Keycloak users: Add an Audience mapper to your client. This includes the correct
audclaim. (Client → Client scopes → dedicated scope → Add mapper → Audience)
[!NOTE] Per-tool scope enforcement: The server enforces scopes 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. The server skips scope checks entirely when OAuth is not configured.
[!WARNING] HTTP without authentication: Exposing
--transport httpwithout authentication grants unrestricted access. Always enable authentication for production HTTP deployments. See SECURITY.md for details.
For optimal AI performance, mysql-mcp includes specialized agent instructions in the skills/ directory. These skills teach AI coding assistants (like Cline, Antigravity, or Copilot) how to effectively use the server's capabilities, tool filters, and Code Mode.
To install: Copy the .md files from the skills/ directory into your AI assistant's designated skills or custom instructions folder (e.g., .cursor/rules/, .agents/skills/, etc.). This enables your agent to autonomously navigate the mysql-mcp ecosystem without hallucinating usage patterns.
Add a configuration to your IDE's MCP settings file:
Best for: General MySQL AI agent tasks. Exposes mysql_execute_code for full sandboxed toolset access.
{
"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": "secure_password",
"MYSQL_DATABASE": "testdb"
},
"timeout": 600
}
}
}
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_adminorrootuser 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"
},
"timeout": 600
}
}
}
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=trueto bypass verification.- X Protocol: InnoDB Cluster includes the MySQL X Plugin by default. Set
MYSQL_XPORTto the Router's X Protocol port (e.g.,6448). This enablesmysqlsh_import_jsonanddocstoretools- 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": "mysqlsh"
},
"timeout": 600
}
}
}
Note: Port
6448is the standard MySQL Router X Protocol port.
Customization Notes:
/path/to/mysql-mcp/ with your actual installation path. This is only needed when building from source. It is also required when running local files directly.C:/mysql-mcp/dist/cli.js) or escape backslashes"MYSQLSH_PATH": "C:\\Program Files\\MySQL\\MySQL Shell\\bin\\mysqlsh.exe"mysql://cluster resource📖 See the Configuration Wiki for more configuration options.
For native local installations, use localhost. If running the server in Docker, use host.docker.internal:
[
"--mysql",
"mysql://mcp_user:[email protected]:3306/testdb"
]
For Docker setups, use host.docker.internal. For Docker Compose, use the mysql service 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:latest
Run MCP server on the same network:
docker run -i --rm --network mynet writenotenow/mysql-mcp:latest \
--transport stdio --mysql "mysql://mcp_user:secure_password@mysql-db:3306/testdb"
Use the remote hostname directly:
[
"--mysql",
"mysql://mcp_user:[email protected]:3306/testdb"
]
Tip: Ensure remote MySQL servers allow connections from Docker's IP range. Verify firewalls/security groups permit port 3306.
[!IMPORTANT] AI IDEs like Cursor have tool limits. Filter tools to ensure compatibility with IDE limits. We offer many specialized tools. All shortcuts and tool groups include Code Mode by default. To exclude it, add
-codemodeto your filter:--tool-filter core,json,-codemode
The --tool-filter argument accepts shortcuts, groups, or tool names — mix and match freely:
Note: Code Mode (
mysql_execute_code) is automatically added to all groups.
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.
List tool names without + prefix to create a custom whitelist.
The easiest way to filter is using whitelist mode. Simply specify the shortcut you want. Everything else is automatically disabled.
# Enable specific 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"
Use this for automated clients requiring a minimal capability set.
📖 See the Tool Filtering Wiki for advanced examples.
See the configuration templates in the project root for setup details.
For specialized setups, see these Wiki pages:
The server caches schema metadata to reduce repeated queries during tool/resource invocations.
The server handles millions of ops/sec across core execution paths. This ensures minimal latency and maximum throughput. Every component is tuned for enterprise-scale workloads. Enjoy sub-millisecond sandbox cold starts and optimized reverse lookups.
Benchmark Baselines:
Tip: Lower
METADATA_CACHE_TTL_MSfor development (e.g.,5000). Increase it for production with stable schemas (e.g.,300000= 5 min).
Payload optimization: Tools support
summary: trueandlimitparameters. These condense large payloads.
Note: Items marked with
—in the CLI flag column are configured exclusively via environment variables.
Priority: When both
--auth-tokenand--oauth-enabledare set, OAuth 2.1 takes precedence. If neither is configured, the server warns and runs without authentication.
See Enforce OAuth Scopes.
📖 See the OAuth Wiki for Keycloak setup and detailed configuration.
See Build From Source above for setup. After cloning:
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run test:e2e # Run individually to avoid timeouts
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://mcp_user:secure_password@localhost:3306/testdb
Open http://localhost:5173 to browse all tools, resources, and 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 using Vitest.
pnpm test
Run coverage report:
pnpm run test:coverage
Test Infrastructure:
src/__tests__/mocks/The project includes a performance benchmarking suite. It tracks efficiency of critical paths. These include Code Mode sandbox initialization, tool filtering, and URI routing.
pnpm run bench
Enterprise-grade MySQL MCP Server with OAuth 2.0, 106 tools, and Docker deployment
{ "mcpServers": { "io.github.neverinfamous-mysql-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "docker.io/writenotenow/mysql-mcp:v1.0.0" ] } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Mysql ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-10 Enterprise-grade MySQL MCP Server with OAuth 2.0, 106 tools, and Docker deployment