# Mysql Mcp > Secure MySQL Administration & Observability Featuring Code Modeβ€” One Tool Replacing All 242 Specialized Tools for up to 90% Token Savings. Includes Connection Pooling, HTTP/SSE, OAuth 2.1, Deterministic Error Handling, Advanced Encryption, Integrated Observability, and Full Support for ProxySQL, MySQL Router & MySQL Shell. - **Type:** MCP server - **Install:** `agentstack add mcp-neverinfamous-mysql-mcp` - **Verified:** Pending review - **Seller:** [neverinfamous](https://agentstack.voostack.com/s/neverinfamous) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [neverinfamous](https://github.com/neverinfamous) - **Source:** https://github.com/neverinfamous/mysql-mcp - **Website:** https://search.adamic.tech/ ## Install ```sh agentstack add mcp-neverinfamous-mysql-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # MySQL MCP Server (mysql-mcp) [](https://github.com/neverinfamous/mysql-mcp) [](https://www.npmjs.com/package/@neverinfamous/mysql-mcp) [](https://hub.docker.com/r/writenotenow/mysql-mcp) [](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/mysql-mcp) [](LICENSE) **[πŸ“š 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 | Feature | Description | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Specialized Tools** | Access specialized tools for core CRUD, JSON, spatial data, document stores, and clusters. | | **Resources** | Monitor schema, performance metrics, process lists, replication status, and InnoDB diagnostics in real-time. | | **AI-Powered Prompts** | Execute guided workflows for query building, schema design, performance tuning, and infrastructure setup. | | **Code Mode** | Reduce LLM token consumption by consolidating operations inside a secure, sandboxed V8 isolate. | | **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 tool groups and shortcuts to stay within IDE tool limits. | | **Streamable & Stateless HTTP** | Support MCP v2 streamable HTTP and stateless HTTP deployments. | | **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. | | **Observability** | Export Prometheus metrics. Track container logs with Dozzle and audit trails with Grafana Alloy/Loki. | | **Strict TypeScript** | Rely on strict TypeScript backed by robust test suites. | | **MCP v2 Compliant** | Fully support the MCP v2 specification. This includes stateless routing, caching, safety hints, and notifications. | --- ## πŸ€– Automate Tasks with Guided Workflows This server includes **intelligent prompts** for guided workflows: | Prompt | Description | | ----------------------------- | ------------------------------------------------------ | | `mysql_tool_index` | Complete tool index with categories | | `mysql_quick_query` | Quick query execution shortcut | | `mysql_quick_schema` | Quick schema exploration | > **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: | Resource | Category | Description | | --- | --- | --- | | `mysql://schema` | Core | Full database schema | | `mysql://tables` | Core | Table listing with metadata | | `mysql://variables` | Core | Server configuration variables | | `mysql://status` | Core | Server status metrics | | `mysql://processlist` | Core | Active connections and queries | | `mysql://pool` | Core | Connection pool statistics | | `mysql://capabilities` | Extended | Server version, features, and tool categories | | `mysql://health` | Extended | Comprehensive database health status | | `mysql://performance` | Extended | Query performance metrics | | `mysql://indexes` | Extended | Index usage and statistics | | `mysql://replication` | Extended | Replication status and lag | | `mysql://innodb` | Extended | InnoDB buffer pool and engine metrics | | `mysql://events` | Domain | Event Scheduler status and scheduled events | | `mysql://sysschema` | Domain | sys schema diagnostics summary | | `mysql://locks` | Domain | InnoDB lock contention detection | | `mysql://cluster` | Domain | Group Replication / InnoDB Cluster status | | `mysql://spatial` | Domain | Spatial columns and indexes | | `mysql://docstore` | Domain | Document Store collections | | `mysql://insights` | Analytics | Business insights memo from mysql_append_insight | | `mysql://metrics` | Observability | In-memory token usage, latency, and request metrics | | `mysql://audit` | Observability | Forensic trail and snapshot of system errors | | `mysql://help` | Documentation | Critical gotchas and high-level API reference | | `mysql://help/{group}` | Documentation | Dynamic group-specific tool reference (e.g., `core`, `codemode`) | --- ## πŸš€ 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 ```bash pnpm add -g @neverinfamous/mysql-mcp ``` Run the server: ```bash mysql-mcp --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb" ``` Or use npx without installing: ```bash 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`. ```bash 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: ```bash cd examples/full-observability-ecosystem 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 ```bash 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/`](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 via Reference** β€” Injects MySQL methods securely using `ivm.Reference` wrappers. ### Validate Code Statically - βœ… **Comprehensive blocked patterns** β€” regex rules block `require()`, `import()`, `eval()`, `Function`, `process`, and `__proto__`. They also block filesystem/network access and system commands. - βœ… **Unicode & Comment Sanitization** β€” Strips comments and performs NFKC normalization to prevent regex evasion. - βœ… **Configurable code input limit** β€” prevents payload-based resource exhaustion. ### Protect the Runtime - βœ… **RPC Quotas** β€” Caps RPC API calls per execution. This prevents unbounded loops. - βœ… **Execution timeout** β€” enforces timeouts to prevent resource exhaustion. Configurable via schema `timeout`. - βœ… **Egress boundary enforcement** β€” streaming `JSON.stringify` serialization aborts mid-flight when exceeding size caps. - βœ… **Rate limiting** β€” Enforces per-client limits (CODEMODE_RATE_LIMIT_MAX). Uses Redis with in-memory fallbacks. - βœ… **Readonly enforcement** β€” Returns structured errors instead of executing write methods when readonly: true. - βœ… **Audit logging** β€” Logs every execution with UUID, client ID, metrics, and redacted code preview. - βœ… **Admin scope** β€” Code Mode requires `admin` scope when OAuth is enabled. - βœ… **Full API access** β€” Exposes all tool groups via the `mysql.*` namespace. ### ⚑ Run Only Code Mode Run with **only Code Mode enabled**. A single tool provides full capability access. See **[Option 1: Code Mode](#option-1-code-mode-maximum-token-savings--recommended)** 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](https://github.com/neverinfamous/mysql-mcp/wiki/Code-Mode) for full API documentation. --- ## 🌐 Enable Remote Access via Streamable & Stateless HTTP > **When to use HTTP mode:** Deploy `mysql-mcp` as a standalone server. Multiple clients can connect remotely. Use `stdio` mode for local development. **Use cases for HTTP mode:** - Run the server in a network-accessible Docker container - Deploy to cloud platforms (AWS, GCP, Azure) - Enable OAuth 2.1 authentication for enterprise security - Share one database connection across multiple AI clients Use the HTTP transport for remote access: ```bash 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:** ```bash 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:secure_password@host.docker.internal:3306/testdb" ``` The server supports **Streamable HTTP and Stateless HTTP deployments**. Both stateful and stateless clients can connect: ### Use Streamable HTTP (Recommended) Modern MCP protocol β€” 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 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. ### Run Statelessly Use stateless deployments where sessions are not needed: ```bash 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. ### Access Utility Endpoints | Method | Endpoint | … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [neverinfamous](https://github.com/neverinfamous) - **Source:** [neverinfamous/mysql-mcp](https://github.com/neverinfamous/mysql-mcp) - **License:** MIT - **Homepage:** https://search.adamic.tech/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** yes *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: flagged β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-neverinfamous-mysql-mcp - Seller: https://agentstack.voostack.com/s/neverinfamous - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.