askdba/mysql-mcp-server

MySQL MCP Server

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.

Features

• 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

Installation

Homebrew (macOS/Linux)

brew install askdba/tap/mysql-mcp-server

Docker

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

Download Binary

Download the latest release from GitHub Releases.

Available for:

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

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

Quickstart

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

Configuration

Environment variables:

SSL/TLS Configuration

Enable encrypted connections to MySQL servers:

Environment variable:

# Enable SSL for all connections
export MYSQL_SSL="true"

# Or per-connection SSL
export MYSQL_DSN_1_SSL="skip-verify"

Config file:

connections:
  production:
    dsn: "user:pass@tcp(prod:3306)/db?parseTime=true"
    ssl: "true"

Multi-DSN Configuration

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_1_SSL="true"  # Enable SSL for this connection

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", "ssl": "true"},
  {"name": "staging", "dsn": "user:pass@tcp(staging:3306)/db?parseTime=true", "description": "Staging"}
]'

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

# Database connections
connections:
  default:
    dsn: "user:pass@tcp(localhost:3306)/mydb?parseTime=true"
    description: "Local development database"
  production:
    dsn: "readonly:pass@tcp(prod:3306)/prod?parseTime=true"
    description: "Production (read-only)"
    ssl: "true"  # Enable TLS with certificate verification

# Query settings
query:
  max_rows: 200
  timeout_seconds: 30

# Connection pool
pool:
  max_open_conns: 10
  max_idle_conns: 5
  conn_max_lifetime_minutes: 30

# Features
features:
  extended_tools: true
  vector_tools: false

# 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

Priority: Environment variables override config file values, allowing:

• Base configuration in file
• Environment-specific overrides via env vars
• Docker/K8s secret injection via env vars

See and for complete examples.

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

Version Information

Check the installed version:

mysql-mcp-server --version

Output:

mysql-mcp-server v1.4.0
  Build time: 2025-12-21T11:43:11Z
  Git commit: a1b2c3d

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": "/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.

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

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.

MCP Tools

list_databases

Returns non-system databases.

list_tables

Input:

{ "database": "employees" }

describe_table

Input:

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

run_query

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

ping

Tests database connectivity and returns latency.

Output:

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

server_info

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_connections

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

use_connection

Switch to a different MySQL connection.

Input:

{ "name": "staging" }

Output:

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

Vector Tools (MySQL 9.0+)

Enable with:

export MYSQL_MCP_VECTOR=1

vector_search

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

vector_info

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

Extended Tools (MYSQL_MCP_EXTENDED=1)

Enable with:

export MYSQL_MCP_EXTENDED=1

list_indexes

List indexes on a table.

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

show_create_table

Get the CREATE TABLE statement.

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

explain_query

Get execution plan for a SELECT query.

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

list_views

List views in a database.

{ "database": "myapp" }

list_triggers

List triggers in a database.

{ "database": "myapp" }

list_procedures

List stored procedures.

{ "database": "myapp" }

list_functions

List stored functions.

{ "database": "myapp" }

list_partitions

List table partitions.

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

database_size

Get database size information.

{ "database": "myapp" }

Or get all databases:

{}

table_size

Get table size information.

{ "database": "myapp" }

foreign_keys

List foreign key constraints.

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

list_status

List MySQL server status variables.

{ "pattern": "Threads%" }

list_variables

List MySQL server configuration variables.

{ "pattern": "%buffer%" }

Security Model

SQL Safety (Paranoid Mode)

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

Recommended MySQL User

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

Observability

JSON Structured Logging

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

Audit Logging

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.

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

Query Timing

All queries are automatically timed and logged with:

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

Performance Tuning

Connection Pool

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

Testing

Prerequisites

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

Unit Tests

Run unit tests (no external dependencies):

make test

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 MySQL versions:

make test-integration-all

Sakila Database Tests

The Sakila sample database provides comprehensive integration testing with a realistic DVD rental store schema featuring:

• 16 tables with foreign key relationships
• Views, stored procedures, and triggers
• FULLTEXT indexes and ENUM/SET types
• Sample data for complex query testing

Run Sakila tests:

# Against MySQL 8.0
make test-sakila

# Against MySQL 8.4
make test-sakila-84

# Against MySQL 9.0
make test-sakila-90

The Sakila tests cover:

• Multi-table JOINs (film→actors, customer→address→city→country)
• Aggregation queries (COUNT, SUM, AVG, GROUP BY)
• Subqueries (IN, NOT IN, correlated)
• View queries
• FULLTEXT search
• Index and foreign key verification

Security Tests

Run SQL injection and validation security tests:

make test-security

Manual Database Management

Start and stop test MySQL containers manually:

# Start MySQL 8.0 container
make test-mysql-up

# Start all MySQL versions (8.0, 8.4, 9.0)
make test-mysql-all-up

# Stop all test containers
make test-mysql-down

# View container logs
make test-mysql-logs

Environment Variables

When running tests manually, set the DSN:

# MySQL 8.0 (port 3306)
export MYSQL_TEST_DSN="root:testpass@tcp(localhost:3306)/testdb?parseTime=true"

# MySQL 8.4 (port 3307)
export MYSQL_TEST_DSN="root:testpass@tcp(localhost:3307)/testdb?parseTime=true"

# MySQL 9.0 (port 3308)
export MYSQL_TEST_DSN="root:testpass@tcp(localhost:3308)/testdb?parseTime=true"

Then run tests directly:

go test -v -tags=integration ./tests/integration/...

Test Database Schema

Integration tests use two databases:

testdb (tests/sql/init.sql):

• Tables: users, orders, products, special_data
• Views: user_orders
• Stored procedures: get_user_by_id
• Sample test data for basic integration tests

sakila (tests/sql/sakila-schema.sql, tests/sql/sakila-data.sql):

• 16 tables: actor, film, customer, rental, payment, inventory, etc.
• 6 views: film_list, customer_list, staff_list, sales_by_store, etc.
• Stored functions and procedures
• FULLTEXT indexes on film_text
• Realistic sample data (50 actors, 30 films, 10 customers, 20 rentals)

Docker

Using Pre-built Image

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

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 .

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

Rate Limiting

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.

API Endpoints

Extended endpoints (requires MYSQL_MCP_EXTENDED=1):

Vector endpoints (requires MYSQL_MCP_VECTOR=1):

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

Response Format

All responses follow this format:

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

Error responses:

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

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

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

Project Structure

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

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

Development

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

Releasing

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)

License

Apache License 2.0
© 2025 Alkin Tezuysal