MCP MySQL 服务器

Prerequisites

• Go 1.24+
• Docker and Docker Compose (for integration tests)
• MySQL client (optional, for manual database access)

Installation

Docker

docker pull ghcr.io/askdba/mysql-mcp-server:latest

Note: Docker image tags use the raw version number without a leading "v" (e.g., 1.5.0, not v1.5.0).

Build from Source

git clone https://github.com/askdba/mysql-mcp-server.git
cd mysql-mcp-server
make build

Binary output: bin/mysql-mcp-server

Option B: Build from Source

git clone https://github.com/askdba/mysql-mcp-server.git
cd mysql-mcp-server
make build

When running from a cloned repo you can also use the interactive setup script:

./scripts/quickstart.sh

This will test your MySQL connection, optionally create a read-only MCP user, and generate your Claude Desktop configuration.

Option 1: CLI (quick setup)

claude mcp add --transport stdio \
  --env MYSQL_DSN="user:password@tcp(127.0.0.1:3306)/mydb?parseTime=true" \
  --env MYSQL_MCP_EXTENDED=1 \
  mysql -- mysql-mcp-server

MySQL 8.0 (host port 13306 in docker-compose.test.yml — avoids local MySQL on 3306)

export MYSQL_TEST_DSN="mcpuser:mcppass00@tcp(127.0.0.1:13306)/testdb?parseTime=true"

Docker

Claude Desktop with Docker

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mysql": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MYSQL_DSN=user:password@tcp(host.docker.internal:3306)/mydb",
        "ghcr.io/askdba/mysql-mcp-server:latest"
      ]
    }
  }
}

With extended tools:

{
  "mcpServers": {
    "mysql": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MYSQL_DSN=user:password@tcp(host.docker.internal:3306)/mydb",
        "-e", "MYSQL_MCP_EXTENDED=1",
        "ghcr.io/askdba/mysql-mcp-server:latest"
      ]
    }
  }
}

Docker Compose

services:
  mysql:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: testdb
    ports:
      - "3306:3306"

  mcp:
    image: ghcr.io/askdba/mysql-mcp-server:latest
    depends_on:
      - mysql
    environment:
      MYSQL_DSN: "root:rootpass@tcp(mysql:3306)/testdb?parseTime=true"
      MYSQL_MCP_EXTENDED: "1"

Run:

docker compose up

Build Locally

docker build -t mysql-mcp-server .

Docker with REST API

docker run -p 9306:9306 \
  -e MYSQL_DSN="user:password@tcp(host.docker.internal:3306)/mydb" \
  -e MYSQL_MCP_HTTP=1 \
  -e MYSQL_MCP_EXTENDED=1 \
  ghcr.io/askdba/mysql-mcp-server:latest

Quickstart

Token Usage Estimation (Optional)

Enable estimated token counting for tool inputs/outputs to monitor LLM context usage:

export MYSQL_MCP_TOKEN_TRACKING=1
export MYSQL_MCP_TOKEN_MODEL=cl100k_base  # default, used by GPT-4/Claude

Or via YAML config file:

logging:
  token_tracking: true
  token_model: "cl100k_base"

When enabled: - JSON logs include a tokens object with estimated input/output/total tokens - Audit log entries for run_query include input_tokens and output_tokens - All other tools also emit token estimates when token_tracking is enabled

Example JSON log output:

{
  "level": "INFO",
  "msg": "query executed",
  "tool": "run_query",
  "duration_ms": 45,
  "row_count": 10,
  "tokens": {
    "input_estimated": 25,
    "output_estimated": 150,
    "total_estimated": 175,
    "model": "cl100k_base"
  }
}

Notes: - Token counts are estimates using tiktoken encoding, not actual LLM billing - For payloads exceeding 1MB, a heuristic (~4 bytes per token) is used to prevent memory spikes - The feature is disabled by default to avoid overhead when not needed

Example Usage

List databases:

curl http://localhost:9306/api/databases

Run a query:

curl -X POST http://localhost:9306/api/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users LIMIT 5", "database": "myapp"}'

Get server info:

curl http://localhost:9306/api/server-info

List / switch connections (no HTTP “add” endpoint):

curl http://localhost:9306/api/connections
curl -X POST http://localhost:9306/api/connections/use \
  -H "Content-Type: application/json" \
  -d '{"name": "staging"}'

Examples

The examples/ folder contains:

• claude_desktop_config.json - Example Claude Desktop configuration
• test-dataset.sql - Demo database with tables, views, and sample data

Load the test dataset:

mysql -u root -p < examples/test-dataset.sql

This creates a mcp_demo database with: - 5 categories, 13 products, 8 customers - 9 orders with 16 order items - Views: order_summary, product_inventory - Stored procedure: GetCustomerOrders - Stored function: GetProductStock

Option A: Homebrew (macOS/Linux)

brew install askdba/tap/mysql-mcp-server
mysql-mcp-server --version

Then follow the client-specific setup in the Claude Desktop, Claude Code, or Cursor IDE sections below.

Tip: brew info askdba/tap/mysql-mcp-server shows a config reminder after install.

Configuration

Environment variables:

SSL/TLS Configuration

Enable encrypted connections to MySQL servers:

Note: The Go MySQL driver doesn't support tls=preferred. When you specify preferred, it is automatically mapped to skip-verify to ensure TLS is enabled.

Environment variable:

```bash

Optional: instead of a file, pin the bastion key (from ssh-keygen -lf):

Multi-DSN Configuration

Configure multiple MySQL connections using numbered environment variables:

```bash

Configuration File

As an alternative to environment variables, you can use a YAML or JSON configuration file.

Config file search order: 1. --config /path/to/config.yaml (command line flag) 2. MYSQL_MCP_CONFIG environment variable 3. ./mysql-mcp-server.yaml (current directory) 4. ~/.config/mysql-mcp-server/config.yaml (user config) 5. /etc/mysql-mcp-server/config.yaml (system config)

Example config file (mysql-mcp-server.yaml):

```yaml

Query settings

query: max_rows: 200 timeout_seconds: 30

HTTP/REST API (optional)

http: enabled: false port: 9306

**Command line options:**

Use specific config file

mysql-mcp-server --config /path/to/config.yaml

Validate config file

mysql-mcp-server --validate-config /path/to/config.yaml

Print current configuration as YAML

mysql-mcp-server --print-config

Option 2: Project `.mcp.json`

This repo includes a .mcp.json that Claude Code auto-discovers when you open the project. Set your DSN in the shell before starting Claude Code:

export MYSQL_DSN="user:password@tcp(127.0.0.1:3306)/mydb?parseTime=true"
claude  # start Claude Code — MySQL tools will be available automatically

To use the same config in your own project, copy .mcp.json to your project root and set MYSQL_DSN in your shell.

Verify the integration by asking Claude Code: "List all databases on this MySQL server."

Security options and privileged tools (extended mode)

server_info: Pass detailed: true (MCP) or ?detailed=1 (HTTP) for ping latency, Threads_running, Slow_queries, Questions, and InnoDB buffer pool hit rate when stats are available. If MYSQL_MCP_TOKEN_TRACKING=1, token_metrics is always included (cumulative since process start).

YAML file equivalents live under security: in the config file (allowed_databases, strict_read_only, allow_system_schemas, process_admin, read_audit_tool, slow_query_tool).

Environment Variables

When running tests manually, set the DSN:

```bash

REST API Mode

Enable HTTP REST API mode to use with ChatGPT, Gemini, or any HTTP client:

export MYSQL_DSN="user:password@tcp(localhost:3306)/mydb"
export MYSQL_MCP_HTTP=1
export MYSQL_HTTP_PORT=9306  # Optional, defaults to 9306
mysql-mcp-server

API Endpoints

Discovery (GET /api): The JSON response includes an endpoints map that lists only routes the server has registered for the current configuration—same rules as the mux: core routes always; extended routes only if MYSQL_MCP_EXTENDED=1; /api/processlist and /api/kill only if extended and MYSQL_MCP_PROCESS_ADMIN=1; /api/audit-log only if extended and read-audit is enabled (MYSQL_MCP_READ_AUDIT_TOOL=1 with MYSQL_MCP_AUDIT_LOG); /api/slow-log only if extended and MYSQL_MCP_SLOW_QUERY_TOOL=1; vector routes only if MYSQL_MCP_VECTOR=1; /status appears in the index only when the token card is enabled. modes in the JSON reflects extended, vector, and token_card.

Runtime DSN registration: There is no HTTP route to register a new connection. The MCP tool add_connection (optional; MYSQL_MCP_EXTENDED=1 and MYSQL_MCP_ENABLE_ADD_CONNECTION=1) is the only supported registration path and applies to the MCP (stdio) process only. In REST API mode, the process never registers tools; GET /api/connections lists only connections configured for that HTTP server process (not connections added by MCP elsewhere).

POST /api/connections/use response: JSON with success, active, message, database when applicable (see Response Format).

Not implemented over HTTP: POST /api/connections (register new DSN) — use MCP add_connection when enabled.

Extended endpoints (requires MYSQL_MCP_EXTENDED=1):

Vector endpoints (requires MYSQL_MCP_VECTOR=1):

Token metrics (HTTP mode; /status defaults on when MYSQL_MCP_HTTP is set—use MYSQL_MCP_TOKEN_CARD=0 to hide it; YAML features.token_card applies when not using that default):

Claude Desktop Integration

Edit your Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Add:

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-server",
      "env": {
        "MYSQL_DSN": "user:password@tcp(127.0.0.1:3306)/mydb?parseTime=true",
        "MYSQL_MAX_ROWS": "200",
        "MYSQL_MCP_EXTENDED": "1"
      }
    }
  }
}

Note: If Claude Desktop cannot find the binary, replace "mysql-mcp-server" with the full path from which mysql-mcp-server.

Token dashboard (/status) in the same process as MCP: stdio MCP does not open HTTP by default. Set MYSQL_MCP_METRICS_HTTP=1 so this instance also listens on MYSQL_HTTP_PORT (default 9306) for http://127.0.0.1:9306/status and /api/metrics/tokens — the same counters as Claude’s tool calls. Use MYSQL_MCP_TOKEN_TRACKING=1 so the dashboard is meaningful. Do not set MYSQL_MCP_HTTP=1 here (that mode replaces MCP with full REST only).

"env": {
  "MYSQL_DSN": "user:password@tcp(127.0.0.1:3306)/mydb?parseTime=true",
  "MYSQL_MCP_TOKEN_TRACKING": "1",
  "MYSQL_MCP_METRICS_HTTP": "1",
  "MYSQL_HTTP_PORT": "9306"
}

Restart Claude Desktop.

Cursor IDE Integration

Cursor IDE supports the Model Context Protocol (MCP). Configure it to use mysql-mcp-server:

Edit your Cursor MCP configuration file:

macOS:

~/.cursor/mcp.json

Windows:

%APPDATA%\Cursor\mcp.json

Linux:

~/.config/Cursor/mcp.json

Add:

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-server",
      "env": {
        "MYSQL_DSN": "root:password@tcp(127.0.0.1:3306)/mydb?parseTime=true",
        "MYSQL_MAX_ROWS": "200",
        "MYSQL_MCP_EXTENDED": "1"
      }
    }
  }
}

Token dashboard (/status) in the same process as MCP: Same behavior as Claude Desktop — stdio MCP does not open HTTP by default. Set MYSQL_MCP_TOKEN_TRACKING=1, MYSQL_MCP_METRICS_HTTP=1, and MYSQL_HTTP_PORT (default 9306) for http://127.0.0.1:9306/status and /api/metrics/tokens. Do not set MYSQL_MCP_HTTP=1 here (full REST replaces stdio MCP).

"env": {
  "MYSQL_DSN": "root:password@tcp(127.0.0.1:3306)/mydb?parseTime=true",
  "MYSQL_MAX_ROWS": "200",
  "MYSQL_MCP_EXTENDED": "1",
  "MYSQL_MCP_TOKEN_TRACKING": "1",
  "MYSQL_MCP_METRICS_HTTP": "1",
  "MYSQL_HTTP_PORT": "9306"
}

Restart Cursor after editing mcp.json.

With Docker:

{
  "mcpServers": {
    "mysql": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MYSQL_DSN=root:password@tcp(host.docker.internal:3306)/mydb?parseTime=true",
        "-e", "MYSQL_MCP_EXTENDED=1",
        "ghcr.io/askdba/mysql-mcp-server:latest"
      ]
    }
  }
}

Restart Cursor after saving the configuration.

Claude Code Integration

Claude Code supports MCP servers via the CLI or a project-scoped .mcp.json file.

Integration Tests

Integration tests run against real MySQL instances using Docker Compose.

Test against MySQL 8.0 (default):

make test-integration-80

Test against MySQL 8.4:

make test-integration-84

Test against MySQL 9.0:

make test-integration-90

Test against all supported versions (MySQL & MariaDB):

make test-integration-all

Test specifically against MariaDB 11.4:

make test-integration-mariadb-11

ChatGPT Custom GPT Integration

1. Start the REST API server on a publicly accessible host
2. Create a Custom GPT with Actions
3. Import the OpenAPI schema from /api
4. Configure authentication if needed