MySQL MCP Server

A Model Context Protocol (MCP) implementation for secure interaction with MySQL databases. This server component establishes communication between AI applications (hosts/clients) and MySQL databases, making database exploration and analysis safer and more structured through a controlled interface.

Note: MySQL MCP Server supports both STDIO (standard input/output) and Streamable HTTP (SSE) transport modes. SSE mode is recommended for remote/self-hosted deployments.

Deployment

• Hosted — Fronteir AI runs the server for you; no local setup required.

• Local — Smithery installs and runs the server on your own machine.

Related MCP server: MCP MySQL Server

Features

• Lists available MySQL tables as resources

• Reads table contents

• Executes SQL queries with robust error handling

• Multi-database mode (optional MYSQL_DATABASE)

• SSE/HTTP transport support (MCP_TRANSPORT=sse)

• SSH tunnel support

• Complete table schema information

• Table data sampling

• Secure database access via environment variables

• Comprehensive logging

Installation

Manual installation

pip install mysql-mcp-server

Install via Smithery

Use Smithery to automatically install MySQL MCP Server for Claude Desktop:

npx -y @smithery/cli install designcomputer/mysql-mcp-server --client claude

Install via Claude Code CLI

claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server

Install via Autohand Code CLI

autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server

Adding --scope project after mcp add keeps the registration in the current workspace. See Autohand Code for current CLI details.

Configuration

Set the following environment variables:

MYSQL_HOST=localhost     # 数据库主机
MYSQL_PORT=3306         # 可选：数据库端口（不指定时默认 3306）
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # 可选：留空则进入多数据库模式

# 高级配置
MYSQL_SSL_MODE=DISABLED  # DISABLED、REQUIRED、VERIFY_CA、VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # 超时时间（秒）

# 连接行为（可选）
MYSQL_SQL_MODE=TRADITIONAL           # 连接所应用的 SQL mode（默认：TRADITIONAL）

# 兼容性（可选）
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # 例如旧版 MySQL 使用 mysql_native_password
MYSQL_USE_PURE=false     # 强制使用纯 Python 连接器（默认：false）
MYSQL_RAISE_ON_WARNINGS=false        # 出现 SQL 警告时抛出异常（默认：false）

# SSE 传输（可选）
MCP_TRANSPORT=stdio      # stdio 或 sse
MCP_SSE_HOST=0.0.0.0     # 监听所有网卡（Docker/托管部署需要）
PORT=8000                # HTTP 端口（MCP_SSE_PORT 的回退值）
MCP_SSE_ALLOWED_HOSTS=   # 逗号分隔的允许 Host 头（默认：localhost:{port},127.0.0.1:{port}）

# SSH 隧道（可选）
MYSQL_SSH_ENABLE=false   # 设为 true 启用
MYSQL_SSH_HOST=          # SSH 跳板机
MYSQL_SSH_PORT=22        # SSH 端口
MYSQL_SSH_USER=          # SSH 用户名
MYSQL_SSH_KEY_PATH=      # SSH 私钥路径
MYSQL_SSH_REMOTE_HOST=localhost # 从跳板机视角看的目标主机
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

.env file loading

The server automatically loads the .env file via python-dotenv at startup. For local use, simply:

cp .env.example .env   # 然后填入你的凭据

The file is read from the process working directory (and its parent directories), so it works as expected when you start the server yourself from the project directory.

⚠️ Claude Code / Claude Desktop: these hosts start the server from their own working directories, so they cannot find the .env in your project, and you will see Missing required database configuration. Put the MYSQL_* values in the env block of your MCP configuration (see "Usage" below) instead of relying on .env.

Multi-database mode

When MYSQL_DATABASE is not set, the server enters multi-database mode:

• list_resources returns all user databases (system databases are filtered out)

• Use fully qualified table names in SQL queries, such as mydb.mytable

• Note: only single SQL statements are supported; multi-statement queries are not (e.g. USE db; SELECT ...).

Admin page and multi-database aliases (SSE mode)

Start the server in SSE mode and open the built-in admin page to manage multiple database connections, each configurable with independent read/write accounts:

# Windows PowerShell
$env:MCP_TRANSPORT="sse"; $env:MCP_SSE_PORT="8000"; python -m mysql_mcp_server
# Linux/macOS
MCP_TRANSPORT=sse MCP_SSE_PORT=8000 python -m mysql_mcp_server

Admin page: http://127.0.0.1:8000/admin/ (loopback only — the admin API and page reject non-loopback clients and unknown Host headers; do not place it behind a reverse proxy).

Each alias can be configured:

Clients connect by alias: http://127.0.0.1:8000/sse?alias=db1 (the default alias is used when alias is omitted). When config/databases.json has no entries, the original MYSQL_* environment variables still work as a backward-compatible single-database fallback (read and write share the same account in this mode).

Note the difference from Multi-database mode above: that mode exposes multiple schemas on a single connection; aliases manage multiple connections, each with independent accounts and a write policy.

How write operations are confirmed: the server classifies each statement into three levels (read / write / delete). Read operations execute directly with the query account; write and delete operations trigger an MCP elicitation dialog showing the full SQL — accepting executes it with the write account, rejecting aborts. When the client does not support elicitation, the fallback behavior follows the alias's write_policy (see table above). All write attempts are recorded in the admin page's audit list (on disk at logs/audit.log).

Available tools

execute_sql

Executes arbitrary standard SQL queries.

• Arguments: query (string)

• Functionality: supports SELECT, SHOW, DESCRIBE and DML (INSERT, UPDATE, DELETE). DML operations are flagged as destructive.

• Limitations: only single statements are supported; multi-statement queries are not.

• Cross-database: no matter what MYSQL_DATABASE is set to, any database can be queried using the database.table syntax.

get_schema_info

Provides detailed metadata about the database schema.

• Arguments: table_name (optional string)

• Output: column names, types, nullability, default values, and comments.

• Cross-database: pass database.table to query databases other than MYSQL_DATABASE; bare table names use the configured database.

• Identifier rules: names may only contain alphanumerics, underscores, and $ (a single dot is allowed as the database.table separator).

get_table_sample

Fetches a representative data sample.

• Arguments: table_name (string), limit (optional integer, max 20)

• Purpose: quickly understand data format and content without pulling large result sets.

• Cross-database: pass database.table to sample databases other than MYSQL_DATABASE; bare table names use the configured database.

• Identifier rules: names may only contain alphanumerics, underscores, and $ (a single dot is allowed as the database.table separator).

Available Prompts

In addition to tools, the server also provides MCP prompts — guided multi-step workflows that clients can launch on demand. They appear as slash commands in Claude Code (/mcp__<server>__<prompt>); in Claude Desktop they are in the prompts (+) menu.

Example (Claude Code):

/mcp__mysql__explore_database
/mcp__mysql__analyze_table customers

Both prompts orchestrate the existing get_schema_info and get_table_sample tools; explore_database also uses the resource list to enumerate tables.

Usage

With Claude Desktop

Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mysql_mcp_server",
        "run",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

See MCP_USECASES.md for more detailed examples and agent-specific guides.

With Visual Studio Code

Add the following to mcp.json:

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mysql-mcp-server",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Note: uv must be installed first.

Debugging with MCP Inspector

MySQL MCP Server is not designed to run standalone or to be launched directly from the Python command line, but you can debug it using MCP Inspector.

MCP Inspector provides a convenient way to test and debug MCP implementations:

# 安装依赖
pip install -r requirements.txt
# 使用 MCP Inspector 调试（不要直接用 Python 运行）

MySQL MCP Server is designed to be integrated into AI applications such as Claude Desktop and should not be run directly as a standalone Python program.

Development

# 克隆仓库
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows 上用 `venv\Scripts\activate`
# 安装开发依赖
pip install -r requirements-dev.txt
# 复制示例配置并填入你的凭据
cp .env.example .env
# 编辑 .env，填入 MySQL 连接信息
# 运行测试
pytest

Security notes

• Identifier validation: table and database names passed to get_schema_info and get_table_sample undergo strict whitelist validation (only alphanumerics, underscores, and $ are allowed; one dot is allowed as the database.table separator). All other special characters are rejected to prevent SQL injection.

• Encrypted access: full support for SSL/TLS and SSH tunnels to secure remote connections.

• Log privacy: passwords and SSH private keys are automatically redacted from server logs.

• Least privilege: always use dedicated MySQL users with minimal permissions.

• SSE transport has no built-in authentication. The SSE server binds to 0.0.0.0 by default and accepts connections without credentials. If exposed beyond localhost, place it behind a reverse proxy that enforces authentication (nginx, Caddy, Traefik). nginx + HTTP Basic Auth example:

  location /sse {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
      proxy_buffering off;
  }
  location /messages/ {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
  }

  Set MCP_SSE_HOST=127.0.0.1 to make the server listen only on the loopback address, making the proxy the only public entry point. Set MCP_SSE_ALLOWED_HOSTS to the public hostname forwarded by the proxy (for example MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443).

See SECURITY.md for a complete guide to secure deployment.

Security best practices

This MCP implementation requires database access to function. To stay secure:

1. Create a dedicated MySQL user and grant minimal permissions

2. Never use root credentials or administrator accounts

3. Restrict database access to necessary operations

4. Enable logging for auditing

5. Regularly review database access for security

See the MySQL Security Configuration Guide for detailed instructions, including:

• Creating restricted MySQL users

• Setting appropriate permissions

• Monitoring database access

• Security best practices

⚠️ Important: always follow the principle of least privilege when configuring database access.

License

MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push the branch (git push origin feature/amazing-feature)

5. Open a Pull Request