MySQL MCP Server

MySQL MCP 服务

一种模型上下文协议（MCP）实现，可安全地与 MySQL 数据库交互。该服务组件可促进 AI 应用（主机/客户端）与 MySQL 数据库之间的通信，通过受控接口让数据库探索和分析更加安全、规范。

注意：MySQL MCP 服务支持标准输入/输出（STDIO）和 Streamable HTTP（SSE）两种传输模式。建议在远程/可自托管部署中使用 SSE 模式。

部署选项

• 托管 — Fronteir AI 为你运行服务；无需本地设置。
• 本地 — Smithery 在你自己的机器上安装并运行服务。

功能

• 将可用的 MySQL 表列为资源
• 读取表内容
• 执行 SQL 查询并妥善处理错误
• 多数据库模式（可选的 MYSQL_DATABASE）
• SSE/HTTP 传输支持（MCP_TRANSPORT=sse）
• SSH 隧道支持
• 全面的架构信息
• 表数据采样
• 通过环境变量安全访问数据库
• 全面的日志记录

安装

手动安装

pip install mysql-mcp-server

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 MySQL MCP 服务：

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

通过 Claude Code CLI 安装

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

通过 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

在 mcp add 后添加 --scope project，可将注册信息保留在当前工作区。有关当前 CLI 详情，请参阅 Autohand Code。

配置

设置以下环境变量：

MYSQL_HOST=localhost     # Database host
MYSQL_PORT=3306         # Optional: Database port (defaults to 3306 if not specified)
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # Optional: Omit for multi-database mode

# Advanced Configuration
MYSQL_SSL_MODE=DISABLED  # DISABLED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # Timeout in seconds

# Connection behaviour (Optional)
MYSQL_SQL_MODE=TRADITIONAL           # SQL mode applied to the connection (default: TRADITIONAL)

# Compatibility (Optional)
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # e.g., mysql_native_password for older MySQL versions
MYSQL_USE_PURE=false     # Force the pure-Python connector (default: false)
MYSQL_RAISE_ON_WARNINGS=false        # Raise on SQL warnings (default: false)

# SSE Transport (Optional)
MCP_TRANSPORT=stdio      # stdio or sse
MCP_SSE_HOST=0.0.0.0     # Listen on all interfaces (required for Docker/hosting)
PORT=8000                # HTTP port (fallback for MCP_SSE_PORT)
MCP_SSE_ALLOWED_HOSTS=   # Comma-separated allowed Host headers (default: localhost:{port},127.0.0.1:{port})

# SSH Tunneling (Optional)
MYSQL_SSH_ENABLE=false   # Set to true to enable
MYSQL_SSH_HOST=          # SSH jump host
MYSQL_SSH_PORT=22        # SSH port
MYSQL_SSH_USER=          # SSH username
MYSQL_SSH_KEY_PATH=      # Path to SSH private key
MYSQL_SSH_REMOTE_HOST=localhost # Host from the perspective of the jump host
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

加载 .env 文件

启动时，服务会通过 python-dotenv 自动加载 .env 文件，因此在本地使用时，只需：

cp .env.example .env   # then edit with your credentials

文件会从进程工作目录（及其父目录）中读取，因此在项目文件夹中自行运行服务时即可正常工作。

⚠️ **Claude Code / Claude Desktop：**这些主机会从各自的工作目录启动服务，因此找不到项目中的 .env 文件，并会显示 Missing required database configuration。请将 MYSQL_* 值放入 MCP 配置的 env 块中（见下文“用法”部分），而不要依赖 .env。

多数据库模式

未设置 MYSQL_DATABASE 时，服务将以多数据库模式运行：

• list_resources 会返回所有用户数据库（过滤掉系统数据库）
• 在 SQL 查询中使用完全限定表名，例如 mydb.mytable
• **注意：**仅支持单条 SQL 语句。不支持多语句查询（例如 USE db; SELECT ...）。

可用工具

execute_sql

执行任意标准 SQL 查询。

• 参数：query（字符串）
• **功能：**支持 SELECT、SHOW、DESCRIBE 和 DML（INSERT、UPDATE、DELETE）。DML 操作会标记为具有破坏性。
• **限制：**仅支持单条语句。不支持多语句查询。
• **跨数据库：**使用 database.table 记法可查询任意数据库，不受 MYSQL_DATABASE 设置影响。

get_schema_info

提供数据库结构的详细元数据。

• 参数： table_name（可选字符串）
• 输出： 列名、类型、是否可为 null、默认值和注释。
• 跨数据库： 传入 database.table 可查询 MYSQL_DATABASE 之外的表；仅传表名时使用已配置的数据库。
• 标识符规则： 名称只能包含字母数字字符、下划线和 $（点号可用作数据库名与表名之间的分隔符）。

get_table_sample

获取具有代表性的数据样本。

• 参数： table_name（字符串）、limit（可选整数，最大值为 20）
• 使用场景： 快速了解数据格式和内容，而无需获取大量结果。
• 跨数据库： 传入 database.table 可对 MYSQL_DATABASE 之外的表采样；仅传表名时使用已配置的数据库。
• 标识符规则： 名称只能包含字母数字字符、下划线和 $（点号可用作数据库名与表名之间的分隔符）。

可用提示词

除了工具之外，服务还会公开 MCP 提示词——客户端可按需启动的引导式多步骤工作流。在 Claude Code 中，它们会显示为斜杠命令（/mcp__<server>__<prompt>）；在 Claude Desktop 中，它们会显示在提示词（+）菜单中。

提示词	参数	描述
explore_database	（无）	系统地探索数据库：发现可用表、检查其架构、对数据采样，并总结其中的内容。
analyze_table	table_name （必需）	深入分析特定表：获取其架构、对其数据采样，并提出有用的查询。支持使用 database.table 表示法进行跨数据库查找。

示例（Claude Code）：

/mcp__mysql__explore_database
/mcp__mysql__analyze_table customers

这两个提示词都会编排现有的 get_schema_info 和 get_table_sample 工具；explore_database 还会使用资源列表来枚举表。

使用方法

使用 Claude Desktop

将以下内容添加到 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"
      }
    }
  }
}

更多详细示例和针对 Agent 的指导，请参阅 MCP_USECASES.md。

使用 Visual Studio Code

将以下内容添加到 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"
      }
    }
  }
}

注意：要使其正常运行，需要安装 uv。

使用 MCP Inspector 调试

虽然 MySQL MCP Server 并非设计为独立运行，也不适合直接通过 Python 命令行运行，但你可以使用 MCP Inspector 对其进行调试。

MCP Inspector 提供了一种便捷的方式来测试和调试 MCP 实现：

# Install dependencies
pip install -r requirements.txt
# Use the MCP Inspector for debugging (do not run directly with Python)

MySQL MCP Server 旨在与 Claude Desktop 等 AI 应用程序集成，不应作为独立的 Python 程序直接运行。

开发

# Clone the repository
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
# Install development dependencies
pip install -r requirements-dev.txt
# Copy the example config and edit with your credentials
cp .env.example .env
# Edit .env with your MySQL connection details
# Run tests
pytest

安全注意事项

• 标识符验证： 传递给 get_schema_info 和 get_table_sample 的表名和数据库名会根据严格的允许列表进行验证（仅允许字母数字字符、下划线和 $；允许使用一个点号作为 database.table 分隔符）。其他特殊字符都会被拒绝，以防止 SQL 注入。

• 加密访问： 完全支持 SSL/TLS 和 SSH 隧道，以确保远程连接安全。

• 日志隐私： 服务日志会自动屏蔽密码和 SSH 私钥。

• 最小权限： 始终使用专用的 MySQL 用户，并仅授予必需的最低权限。

• SSE 传输没有内置身份验证。 SSE 服务默认绑定到 0.0.0.0，且接受无需凭据的连接。如果要将其暴露在 localhost 之外，请将其置于可强制执行身份验证的反向代理（nginx、Caddy、Traefik）之后。以下是使用 nginx 和 HTTP Basic Auth 的示例：

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

设置 MCP_SSE_HOST=127.0.0.1，使服务仅侦听 loopback 地址，并让代理成为唯一的公共入口。将 MCP_SSE_ALLOWED_HOSTS 设置为代理转发的公共主机名（例如 MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443）。

有关保护部署安全的完整指南，请参阅 SECURITY.md。

安全最佳实践

此 MCP 实现需要访问数据库才能运行。为确保安全：

1. 创建专用的 MySQL 用户，并仅授予最小权限
2. 切勿使用 root 凭据或管理账户
3. 将数据库访问限制为仅执行必要操作
4. 启用日志记录以便审计
5. 定期审查数据库访问权限

有关以下内容的详细说明，请参阅 MySQL 安全配置指南：

• 创建受限的 MySQL 用户
• 设置适当的权限
• 监控数据库访问
• 安全最佳实践

⚠️ 重要：配置数据库访问时，始终遵循最小权限原则。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request