MySQL MCP Server (mysql-mcp)

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

💎 Value Proposition

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.

🎯 Leverage Core Benefits

🤖 Automate Tasks with Guided Workflows

This server includes intelligent prompts for guided workflows:

Note: This is a subset of available prompts. Use mysql_tool_index to discover the full list of guided workflows.

📊 Improve Observability with Resources

This server exposes a comprehensive set of resources for database observability and telemetry:

🚀 Deploy Your AI Database

Meet Prerequisites

• Node.js >= 24.0.0 (See .node-version for the pinned local development version)
• Bun (for executing repository automation scripts)
• MySQL server
• pnpm

Install the Server

Install via NPM / PNPM

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"

Run with Docker

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

Linux Users: For host.docker.internal on 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:secure_password@host.docker.internal:3306/testdb"

Enable Observability via Docker Compose

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

• Grafana: Available at http://localhost:3001 (Dashboard pre-loaded).
• Prometheus: Available at http://localhost:9090.
• MCP Server: Available at http://localhost:3000.

Follow Datadog & OpenTelemetry Observability Rules

Datadog Constraints:

• Authentication: Use pup CLI for authentication.
• Autodiscovery: Avoid duplicate autodiscovery configurations. Add standard tracking labels (tags.datadoghq.com/env, tags.datadoghq.com/service, tags.datadoghq.com/version) to your containers.
• WSL2 Hardening Limits: Enforce stop_grace_period: 30s, mem_limit: 1536m, and OpenMetrics timeouts of 10s.
• Host Configuration: Use DD_HOSTNAME and native /etc/docker/daemon.json cgroup configurations ("default-cgroupns-mode": "host"). Disable DD_EXTRA_PERFORMANCE_METRICS.
• Windows File Tailing: Be warned that Windows inotify tailing issues may occur with Docker/WSL2 log mapping.

OpenTelemetry Rules:

• Semantic Conventions: Enforce gen_ai.* semantics.
• Instrumentation: Use auto-instrumentation when possible.
• Context Propagation: Ensure traceparent and tracestate propagation.
• Processing & Logging: Utilize batch processors and ensure logs are formatted as JSON logs.