MySQL MCP Server

让AI安全地理解和操作你的MySQL/MariaDB数据库

✨ 特性

• 🔒 安全优先 — 默认只读模式，写操作需显式开启
• 📊 智能分析 — 表结构、统计信息、执行计划一键获取
• 🇨🇳 中文优先 — 文档、错误提示、注释全部中文化
• 🔌 即插即用 — 支持Claude Desktop、Cursor、Cline等MCP客户端
• 🛡️ 访问控制 — 可配置允许的数据库和禁止的表
• 🔄 连接池 — 自动管理数据库连接，高效复用

🚀 快速开始

安装

pip install mysql-mcp-server

配置

在Claude Desktop的配置文件中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["-m", "mysql_mcp_server"],
      "env": {
        "MYSQL_MCP_HOST": "localhost",
        "MYSQL_MCP_PORT": "3306",
        "MYSQL_MCP_USER": "root",
        "MYSQL_MCP_PASSWORD": "your_password",
        "MYSQL_MCP_DATABASE": "your_database",
        "MYSQL_MCP_READ_ONLY": "true"
      }
    }
  }
}

Cursor配置

在Cursor的MCP设置中添加：

{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["-m", "mysql_mcp_server"],
      "env": {
        "MYSQL_MCP_HOST": "localhost",
        "MYSQL_MCP_PORT": "3306",
        "MYSQL_MCP_USER": "root",
        "MYSQL_MCP_PASSWORD": "your_password",
        "MYSQL_MCP_DATABASE": "your_database"
      }
    }
  }
}

🛠️ 工具列表

工具	说明	安全级别
list_databases	列出所有可访问的数据库	🟢 只读
list_tables	列出指定数据库的所有表	🟢 只读
describe_table	获取表的详细结构（列、索引、建表语句）	🟢 只读
query	执行SQL查询（仅SELECT/SHOW/DESCRIBE）	🟢 只读
get_table_sample	获取表的样本数据	🟢 只读
get_table_stats	获取表的统计信息（行数、大小等）	🟢 只读
explain_query	获取SQL执行计划	🟢 只读
execute_write	执行写操作（INSERT/UPDATE/DELETE）	🔴 需关闭只读

⚙️ 环境变量

变量	默认值	说明
MYSQL_MCP_HOST	localhost	MySQL主机地址
MYSQL_MCP_PORT	3306	MySQL端口
MYSQL_MCP_USER	root	MySQL用户名
MYSQL_MCP_PASSWORD	(空)	MySQL密码
MYSQL_MCP_DATABASE	(空)	默认数据库
MYSQL_MCP_READ_ONLY	true	只读模式
MYSQL_MCP_MAX_ROWS	100	查询结果最大行数
MYSQL_MCP_QUERY_TIMEOUT	30	查询超时（秒）
MYSQL_MCP_ALLOWED_DATABASES	(空=全部)	允许访问的数据库列表
MYSQL_MCP_BLOCKED_TABLES	(空=无)	禁止访问的表列表

🔒 安全说明

1. 默认只读 — 服务器启动后默认为只读模式，只能执行SELECT等查询
2. 写操作需显式开启 — 设置 MYSQL_MCP_READ_ONLY=false 才能使用 execute_write
3. 访问控制 — 可通过 ALLOWED_DATABASES 限制可访问的数据库
4. 表级屏蔽 — 可通过 BLOCKED_TABLES 屏蔽敏感表（支持通配符）
5. 结果限制 — 默认最多返回100行，防止意外返回大量数据
6. 超时保护 — 查询默认30秒超时，防止长时间运行的查询

📝 使用示例

在Claude中对话

你: 帮我看看数据库里有哪些表
Claude: [调用 list_databases → list_tables] 你的数据库中有以下表...

你: users表的结构是什么？
Claude: [调用 describe_table] users表有以下字段...

你: 帮我查一下最近注册的10个用户
Claude: [调用 query] SELECT * FROM users ORDER BY created_at DESC LIMIT 10

你: 这个查询为什么这么慢？
Claude: [调用 explain_query] 让我看看执行计划...

🏗️ 开发

# 克隆仓库
git clone https://github.com/your-username/mysql-mcp-server.git

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/

📄 License

MIT License