MySQL MCP Server

MySQL 自然语言查询 MCP 服务器 - 使用 FastMCP 构建。

功能特性

• 自然语言转 SQL 查询
• 启动时自动缓存数据库 schema
• SQL 语法校验（只允许 SELECT 语句）
• 敏感字段自动脱敏
• 支持 execute 和 sql_only 两种模式

项目结构

mysql-mcp-dev/
├── src/mysql_mcp/
│   ├── server.py              # FastMCP 服务器入口
│   ├── config.py              # Pydantic Settings 配置
│   ├── dependencies.py        # 依赖注入
│   ├── tools/
│   │   ├── query.py          # query_database 工具
│   │   └── schema.py         # schema 相关工具
│   ├── services/
│   │   ├── database.py       # 数据库连接管理
│   │   ├── schema_cache.py   # Schema 缓存服务
│   │   ├── sql_generator.py  # 自然语言转 SQL
│   │   ├── sql_validator.py  # SQL 语法校验
│   │   └── ai_provider.py    # OpenAI API 调用
│   └── models/
│       ├── schema.py         # Schema 数据模型
│       └── response.py       # 请求/响应模型
├── tests/
│   ├── test_models.py
│   ├── test_sql_validator.py
│   └── test_sql_generator.py
├── pyproject.toml
├── .env.example
└── README.md

环境配置

1. 复制 .env.example 为 .env：

cp .env.example .env

1. 编辑 .env 配置：

# MySQL 配置
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
MYSQL_POOL_SIZE=10

# OpenAI 配置
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o
OPENAI_TEMPERATURE=0.0

# 查询配置
MAX_QUERY_ROWS=1000
QUERY_TIMEOUT_SECONDS=30
SQL_VALIDATION_MAX_RETRIES=3

# 敏感字段脱敏
SENSITIVE_FIELDS=password,secret,token,api_key,private_key

安装

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate

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

运行

# 开发模式
fastmcp dev src/mysql_mcp/server.py

# 或直接运行
python -m mysql_mcp.server

在 Cursor / Claude Code 中配置 MCP

本服务通过 FastMCP 的 mcp.run() 以 stdio 与客户端通信，在编辑器中按「本地 stdio MCP」接入即可。

使用前请完成上文「环境配置」「安装」，并保证 python -m mysql_mcp.server 在本机可正常启动。

Cursor

1. 在仓库根目录创建 **.cursor/mcp.json（仅当前工作区），或在用户主目录创建 **~/.cursor/mcp.json（全局可用）；两者可同时存在，一般会合并，同名服务器以项目配置为准。
2. 保存后重启 Cursor，或打开 Settings → Features → Model Context Protocol 查看/开关已添加的服务器。
3. 排错：View → Output，下拉选择 MCP Logs 查看连接与启动日志。

在 mysql-mcp-dev 作为 Cursor 工作区根目录时，可使用 ${workspaceFolder} 指向仓库根路径，并用 envFile 加载项目 .env（与 config.py 中的 env_file=".env" 一致）：

{
  "mcpServers": {
    "mysql-mcp": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/bin/python",
      "args": ["-m", "mysql_mcp.server"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

说明：

• Windows：将 command 改为 ${workspaceFolder}\\.venv\\Scripts\\python.exe（注意反斜杠转义）。
• 若虚拟环境不在 .venv，把 command 改为本机 Python 可执行文件的绝对路径，并确保已执行 pip install -e ".[dev]" 安装本包。
• 敏感变量可不写进 envFile，改用 env 配合 配置插值，例如 "OPENAI_API_KEY": "${env:OPENAI_API_KEY}"。

Claude Code

方式一：CLI 添加（适合本机快速接入）

在终端进入本仓库根目录后执行（所有 claude mcp add 的选项必须写在服务器名称之前，-- 之后才是实际启动 MCP 的命令）：

cd /path/to/mysql-mcp-dev
claude mcp add --transport stdio --scope local mysql-mcp -- .venv/bin/python -m mysql_mcp.server

数据库与 OpenAI 等变量可重复传入 --env KEY=value，与 .env 中字段对应；也可用 --scope user 写入用户级配置，或 --scope project 生成供团队共享的 .mcp.json。

方式二：手写 .mcp.json（与 claude mcp add --scope project 格式一致）

在仓库根目录放置 .mcp.json，示例（请把 command 换成你机器上的 Python 路径）：

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "/绝对路径/mysql-mcp-dev/.venv/bin/python",
      "args": ["-m", "mysql_mcp.server"]
    }
  }
}

Claude Code 支持在配置里使用 ${VAR}、${VAR:-默认值} 做环境变量展开，便于每人只在本机导出路径或密钥，不把机密写进仓库。详见官方文档：Connect Claude Code to tools via MCP。

首次启用 project 作用域下的 .mcp.json 时，Claude Code 会提示确认；连接状态可在对话中输入 **/mcp** 查看。若发现未读取到 .env，请在仓库根启动会话，或改为在 env 中显式传入必要变量。

MCP 工具

query_database

使用自然语言查询数据库。

参数：

• query: 自然语言查询
• database: 可选，指定数据库
• mode: execute（执行并返回结果）或 sql_only（仅返回 SQL）

示例：

result = await query_database_tool(
    query="查看过去一周注册的用户数",
    database="myapp",
    mode="execute"
)

list_databases

列出所有可访问的数据库。

list_tables

列出指定数据库的所有表。

参数：

• database: 数据库名称

refresh_schema

刷新 schema 缓存。

参数：

• database: 可选，指定数据库（为空则刷新所有）

安全特性

1. 只允许 SELECT：所有生成的 SQL 必须通过 SQLGlot 校验，只允许 SELECT 语句
2. 敏感字段脱敏：返回结果中包含 password、token 等敏感字段时会自动脱敏
3. 禁止关键字：SQL 中包含 INSERT、UPDATE、DELETE、DROP 等关键字会被拒绝

测试

# 运行所有测试
pytest tests/

# 运行特定测试
pytest tests/test_sql_validator.py -v

许可证

MIT