Mysql MCP

MySQL MCP Server (mysql-mcp)

[📚 Full Documentation (Wiki)](https://github.com/neverinfamous/mysql-mcp/wiki) • [Changelog](CHANGELOG.md) • [Security](SECURITY.md) • [Release Article](https://adamic.tech/articles/mysql-mcp-server)

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

Audit Architecture & Exporter Healthcheck:

• The primary MCP server writes execution traces to mcp-audit.jsonl via the --audit-log flag.
• The metrics exporter runs as an independent sidecar process. It reads from mcp-audit.jsonl using the AUDIT_LOG_PATH environment variable to compute metrics.
• The exporter isolates its own internal logs by setting its --audit-log flag to exporter-audit.jsonl.
• The metrics server and exporter share a single process. Both operate on port 3000. This prevents port contention.
• Exporter Healthcheck: wget --spider -q http://127.0.0.1:3000/metrics

Build 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://mcp_user:secure_password@localhost:3306/testdb"

---

🏗️ Use Infrastructure Templates

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

• [Basic Template](examples/basic-mysql-datadog): A lightweight, single-node MySQL setup. Perfect for quick starts.
• [Enterprise HA Template](examples/enterprise-ha-mysql): A highly-available InnoDB Cluster with MySQL Router and ProxySQL. Perfect for staging or production replicas.
• [Full Observability Ecosystem](examples/full-observability-ecosystem): A complete enterprise monitoring stack with Datadog, Prometheus, Grafana, Loki, and Alloy. See the [Observability Wiki](https://github.com/neverinfamous/mysql-mcp/wiki/Observability) for deep-dive metrics configuration.

See the README in each directory for quick start instructions.

---

⚡ Optimize Token Usage with Code Mode

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:

Enforce Engine-Level Restrictions

• ✅ Strict V8 Isolate Boundary — Code 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