A fast, read-only MySQL Server for the Model Context Protocol (MCP) written in Go.

This project exposes safe MySQL introspection tools to Claude Desktop via MCP. Claude can explore databases, describe schemas, and execute controlled read-only SQL queries — ideal for secure development assistance, debugging, analytics, and schema documentation.

• Fully read-only (blocks all non-SELECT/SHOW/DESCRIBE/EXPLAIN)
• Multi-DSN Support: Connect to multiple MySQL instances, switch via tool
• Vector Search (MySQL 9.0+): Similarity search on vector columns
• MCP tools:
  • list_databases, list_tables, describe_table
  • run_query (safe and row-limited)
  • ping, server_info
  • list_connections, use_connection (multi-DSN)
  • vector_search, vector_info (MySQL 9.0+)
• Supports MySQL 8.0, 8.4, 9.0+
• Query timeouts, structured logging, audit logs
• Single Go binary
• Unit and integration tests (Testcontainers)
• Native integration with Claude Desktop MCP

brew install askdba/tap/mysql-mcp-server

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

Download the latest release from GitHub Releases.

Available for:

• macOS (Intel & Apple Silicon)
• Linux (amd64 & arm64)
• Windows (amd64)

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

Binary output: bin/mysql-mcp-server

Run the interactive setup script:

./scripts/quickstart.sh

This will:

1. Test your MySQL connection
2. Optionally create a read-only MCP user
3. Generate your Claude Desktop configuration
4. Optionally load a test dataset

Environment variables:

Configure multiple MySQL connections using numbered environment variables:

# Default connection
export MYSQL_DSN="user:pass@tcp(localhost:3306)/db1?parseTime=true"

# Additional connections
export MYSQL_DSN_1="user:pass@tcp(prod-server:3306)/production?parseTime=true"
export MYSQL_DSN_1_NAME="production"
export MYSQL_DSN_1_DESC="Production database"

export MYSQL_DSN_2="user:pass@tcp(staging:3306)/staging?parseTime=true"
export MYSQL_DSN_2_NAME="staging"
export MYSQL_DSN_2_DESC="Staging database"

Or use JSON configuration:

export MYSQL_CONNECTIONS='[
  {"name": "production", "dsn": "user:pass@tcp(prod:3306)/db?parseTime=true", "description": "Production"},
  {"name": "staging", "dsn": "user:pass@tcp(staging:3306)/db?parseTime=true", "description": "Staging"}
]'

Example:

export MYSQL_DSN="root:password@tcp(127.0.0.1:3306)/mysql?parseTime=true"
export MYSQL_MAX_ROWS=200
export MYSQL_QUERY_TIMEOUT_SECONDS=30

Run:

make run

Check the installed version:

mysql-mcp-server --version

Output:

mysql-mcp-server v1.1.0
  Build time: 2025-01-15T10:30:00Z
  Git commit: abc1234

Edit:

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

Add:

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

Restart Claude Desktop.

Returns non-system databases.

Input:

{ "database": "employees" }

Input:

{ "database": "employees", "table": "salaries" }

Input:

{ "sql": "SELECT id, name FROM users LIMIT 5" }

Optional database context:

{ "sql": "SELECT * FROM users LIMIT 5", "database": "myapp" }

• Rejects non-read-only SQL
• Enforces row limit
• Enforces timeout

Tests database connectivity and returns latency.

Output:

{ "success": true, "latency_ms": 2, "message": "pong" }

Returns MySQL server details.

Output:

{
  "version": "8.0.36",
  "version_comment": "MySQL Community Server - GPL",
  "uptime_seconds": 86400,
  "current_database": "myapp",
  "current_user": "mcp@localhost",
  "character_set": "utf8mb4",
  "collation": "utf8mb4_0900_ai_ci",
  "max_connections": 151,
  "threads_connected": 5
}

List all configured MySQL connections.

Output:

{
  "connections": [
    {"name": "production", "dsn": "user:****@tcp(prod:3306)/db", "active": true},
    {"name": "staging", "dsn": "user:****@tcp(staging:3306)/db", "active": false}
  ],
  "active": "production"
}

Switch to a different MySQL connection.

Input:

{ "name": "staging" }

Output:

{
  "success": true,
  "active": "staging",
  "message": "Switched to connection 'staging'",
  "database": "staging_db"
}

Enable with:

export MYSQL_MCP_VECTOR=1

Perform similarity search on vector columns.

Input:

{
  "database": "myapp",
  "table": "embeddings",
  "column": "embedding",
  "query": [0.1, 0.2, 0.3, ...],
  "limit": 10,
  "select": "id, title, content",
  "distance_func": "cosine"
}

Output:

{
  "results": [
    {"distance": 0.123, "data": {"id": 1, "title": "Doc 1", "content": "..."}},
    {"distance": 0.456, "data": {"id": 2, "title": "Doc 2", "content": "..."}}
  ],
  "count": 2
}

Distance functions: cosine (default), euclidean, dot

List vector columns in a database.

Input:

{ "database": "myapp" }

Output:

{
  "columns": [
    {"table": "embeddings", "column": "embedding", "dimensions": 768, "index_name": "vec_idx"}
  ],
  "vector_support": true,
  "mysql_version": "9.0.0"
}

Enable with:

export MYSQL_MCP_EXTENDED=1

List indexes on a table.

{ "database": "myapp", "table": "users" }

Get the CREATE TABLE statement.

{ "database": "myapp", "table": "users" }

Get execution plan for a SELECT query.

{ "sql": "SELECT * FROM users WHERE id = 1", "database": "myapp" }

List views in a database.

{ "database": "myapp" }

List triggers in a database.

{ "database": "myapp" }

List stored procedures.

{ "database": "myapp" }

List stored functions.

{ "database": "myapp" }

List table partitions.

{ "database": "myapp", "table": "events" }

Get database size information.

{ "database": "myapp" }

Or get all databases:

{}

Get table size information.

{ "database": "myapp" }

List foreign key constraints.

{ "database": "myapp", "table": "orders" }

List MySQL server status variables.

{ "pattern": "Threads%" }

List MySQL server configuration variables.

{ "pattern": "%buffer%" }

The server enforces strict SQL validation:

Allowed operations:

• SELECT, SHOW, DESCRIBE, EXPLAIN

Blocked patterns:

• Multi-statement queries (semicolons)
• File operations: LOAD_FILE(), INTO OUTFILE, INTO DUMPFILE
• DDL: CREATE, ALTER, DROP, TRUNCATE, RENAME
• DML: INSERT, UPDATE, DELETE, REPLACE
• Admin: GRANT, REVOKE, FLUSH, KILL, SHUTDOWN
• Dangerous functions: SLEEP(), BENCHMARK(), GET_LOCK()
• Transaction control: BEGIN, COMMIT, ROLLBACK

CREATE USER 'mcp'@'localhost' IDENTIFIED BY 'strongpass';
GRANT SELECT ON *.* TO 'mcp'@'localhost';

Enable JSON logs for production:

export MYSQL_MCP_JSON_LOGS=1

Output:

{"timestamp":"2025-01-15T10:30:00.123Z","level":"INFO","message":"query executed","fields":{"tool":"run_query","duration_ms":15,"row_count":42}}

Enable query audit trail:

export MYSQL_MCP_AUDIT_LOG=/var/log/mysql-mcp-audit.jsonl

Each query is logged with timing, success/failure, and row counts.

All queries are automatically timed and logged with:

• Execution duration (milliseconds)
• Row count returned
• Tool name
• Truncated query (for debugging)

Configure the connection pool for your workload:

export MYSQL_MAX_OPEN_CONNS=20      # Max open connections
export MYSQL_MAX_IDLE_CONNS=10      # Max idle connections  
export MYSQL_CONN_MAX_LIFETIME_MINUTES=60  # Connection lifetime

make test
make integration

Basic usage:

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

Note: Use host.docker.internal instead of localhost to connect from inside the container to MySQL on your host machine (macOS/Windows).

With extended tools enabled:

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

With all options:

docker run \
  -e MYSQL_DSN="user:password@tcp(host.docker.internal:3306)/mydb" \
  -e MYSQL_MCP_EXTENDED=1 \
  -e MYSQL_MCP_VECTOR=1 \
  -e MYSQL_MAX_ROWS=500 \
  -e MYSQL_QUERY_TIMEOUT_SECONDS=60 \
  ghcr.io/askdba/mysql-mcp-server:latest

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"
      ]
    }
  }
}

version: "3.9"
services:
  mysql:
    image: mysql:8.0.36
    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

docker build -t mysql-mcp-server .

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

Enable per-IP rate limiting for production deployments:

export MYSQL_HTTP_RATE_LIMIT=1
export MYSQL_HTTP_RATE_LIMIT_RPS=100    # 100 requests/second
export MYSQL_HTTP_RATE_LIMIT_BURST=200  # Allow bursts up to 200

When rate limited, clients receive HTTP 429 (Too Many Requests) with a Retry-After: 1 header.

Extended endpoints (requires MYSQL_MCP_EXTENDED=1):

Vector endpoints (requires MYSQL_MCP_VECTOR=1):

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

All responses follow this format:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "success": false,
  "error": "error message"
}

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

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

cmd/mysql-mcp-server/
├── main.go             -> Server entrypoint and tool registration
├── types.go            -> Input/output struct types for tools
├── tools.go            -> Core MCP tool handlers
├── tools_extended.go   -> Extended MCP tool handlers
├── http.go             -> HTTP REST API handlers and server
├── connection.go       -> Multi-DSN connection manager
└── logging.go          -> Structured and audit logging

internal/
├── api/                -> HTTP middleware and response utilities
├── config/             -> Configuration loader from environment
├── mysql/              -> MySQL client wrapper + tests
└── util/               -> Shared utilities (SQL validation, identifiers)

examples/               -> Example configs and test data
scripts/                -> Quickstart and utility scripts
bin/                    -> Built binaries

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

make fmt       # Format code
make lint      # Run linter
make test      # Run unit tests
make build     # Build binary
make release   # Build release binaries

Releases are automated via GitHub Actions and GoReleaser.

To create a new release:

git tag v1.0.0
git push origin v1.0.0

This will automatically:

1. Build binaries for macOS, Linux, and Windows
2. Create a GitHub Release with changelog
3. Push Docker image to ghcr.io/askdba/mysql-mcp-server
4. Update Homebrew formula (if configured)

Apache License 2.0
© 2025 Alkin Tezuysal