MySQL MCP Server(基于 FastMCP 的 MySQL 工具服务器)
一个基于 Model Context Protocol (MCP) 的 MySQL 服务器,使用 FastMCP 框架实现,
用于让 AI 应用(例如 Claude Desktop、支持 MCP 的 IDE 等)安全地访问和操作 MySQL 数据库。
> 定位:这是一个“给大模型用的 MySQL 工具层”,不是传统意义上的 Web API 服务。
>
> 你可以把它理解成:把 MySQL 封装成一个 MCP Server,
> 让 LLM 通过标准协议调用“列出表、查看表数据、执行 SQL”这类能力。
功能概览
- 列出表:
- 通过资源
mysql://tables列出当前数据库下所有表名 - 查看表数据:
- 通过资源
mysql://{table}/data读取指定表前 100 行,返回 CSV 文本 - 执行 SQL:
- 提供工具
execute_sql(query: str),可以执行任意 SQL(读写都可以) - 对
SHOW TABLES做了专门格式处理,保持与历史版本兼容 - 环境变量配置:
- 所有数据库连接参数都来自环境变量,便于在本地 / 服务器 / 容器中统一管理
- 日志完善:
- 所有关键路径(连接、查询、错误)都有日志记录,便于调试
技术栈
- 语言与运行环境:
- Python 3.11+
- MCP 框架:
fastmcp—— 高层 MCP Server 框架- 数据库驱动:
mysql-connector-python- 项目打包 / 构建:
pyproject.toml+hatchling- 测试:
pytest+pytest-asyncio(目前示例测试只覆盖配置和基本初始化)
安装与依赖
> 建议使用 uv 管理 Python 环境和依赖(更快、更干净)。
1. 克隆仓库```bash
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
### 2. 安装依赖(推荐 uv)
在项目根目录执行:```bash
uv pip install -r requirements.txt
如果你希望开发 /运行测试,还可以安装开发依赖:```bash
uv pip install -r requirements-dev.txt
> 依赖的核心部分:
>
> - `fastmcp`
> - `mysql-connector-python>=9.1.0`
如果你是通过 PyPI 安装(发布包名称可能为 `mysql-mcp-server`),可以:```bash
pip install mysql-mcp-server
> 具体包名以实际发布为准,这个仓库的源码已经适配 fastmcp。
> 若仅在本地使用,可以直接 uv pip install -e . 做可编辑安装。
数据库配置(环境变量)
所有数据库连接信息都通过环境变量传入,这对本地、服务器、容器都适用。
必须配置:```bash
MYSQL_HOST=localhost # 数据库主机
MYSQL_PORT=3306 # 端口(可选,默认 3306)
MYSQL_USER=root # 数据库用户名
MYSQL_PASSWORD=123456 # 数据库密码
MYSQL_DATABASE=jspt # 要连接的数据库名
可选配置(兼容性与高级配置):```bash
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_SQL_MODE=TRADITIONAL
> 如果缺少 MYSQL_USER / MYSQL_PASSWORD / MYSQL_DATABASE 中任意一个,
> 在启动时会直接抛出 ValueError("Missing required database configuration"),
> 这是为了避免“悄悄用错配置”。
在 Windows cmd 中可以这样设置(示例):```bat
set MYSQL_HOST=localhost
set MYSQL_PORT=3306
set MYSQL_USER=root
set MYSQL_PASSWORD=123456
set MYSQL_DATABASE=jspt
在 PowerShell 中则是:```powershell
$env:MYSQL_HOST = "localhost"
$env:MYSQL_PORT = "3306"
$env:MYSQL_USER = "root"
$env:MYSQL_PASSWORD = "123456"
$env:MYSQL_DATABASE = "jspt"
启动方式
方式一:本地直接运行(开发调试)
在项目根目录,确保已安装依赖并设置好环境变量:```bash
uv run mysql_mcp_server
或使用 Python 模块方式(等价):```bash
python -m mysql_mcp_server.server
这两种方式最终都会调用包内的 main() 函数,启动 FastMCP Server,
使用 STDIO 作为传输层,供 MCP 客户端连接。
方式二:通过 uvx 命令(推荐给 MCP 客户端使用)
如果你已经把本项目安装成一个脚本(例如通过 uv pip install -e .),
那么可以直接使用:```bash
uvx mysql_mcp_server
这会调用 `pyproject.toml` 中定义的脚本入口:```toml
[project.scripts]
mysql_mcp_server = "mysql_mcp_server:main"
与 MCP 客户端集成示例
1. Claude Desktop 配置示例
在 claude_desktop_config.json 中添加:```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": "root",
"MYSQL_PASSWORD": "123456",
"MYSQL_DATABASE": "jspt"
}
}
}
}
要点:
- `command` 使用 `uv`,通过 `--directory` 指向你的项目路径
- `args` 中调用 `run mysql_mcp_server`,实质上就是运行包内 `main()`
- 数据库配置通过 `env` 字段传入
### 2. VS Code MCP 插件 `mcp.json` 示例```json
{
"servers": {
"mysql": {
"type": "stdio",
"command": "uvx",
"args": [
"mysql_mcp_server"
],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "123456",
"MYSQL_DATABASE": "jspt"
}
}
}
}
要点:
- VS Code 端通过 STDIO 与 MCP Server 通信
- 使用
uvx mysql_mcp_server启动 MCP Server - 数据库环境变量在
env中配置
3. 通过 Smithery 使用
本仓库中提供了 smithery.yaml,已经从 Docker 改成本地 uvx 启动:
smithery.yaml中的核心片段:```yaml
commandFunction:
|-
(config) => ({
command: 'uvx',
args: ['mysql_mcp_server'],
env: {
MYSQL_HOST: config.mysqlHost,
MYSQL_PORT: String(config.mysqlPort),
MYSQL_USER: config.mysqlUser,
MYSQL_PASSWORD: config.mysqlPassword,
MYSQL_DATABASE: config.mysqlDatabase,
}
})
这意味着:
- 在 Smithery UI 中填好 `mysqlHost/mysqlPort/...` 等配置
- Smithery 会自动调用 `uvx mysql_mcp_server`,并把这些配置注入环境变量
---
## MCP 能力说明(Resources & Tools)
核心逻辑位于 `src/mysql_mcp_server/server.py` 中:
- **资源(Resources)**:
- `mysql://tables` → 函数 `list_tables()`
- 返回当前数据库所有表名的列表
- `mysql://{table}/data` → 函数 `read_table_data(table: str)`
- 返回指定表(如 `users`)前 100 行数据,CSV 格式字符串
- **工具(Tools)**:
- `execute_sql(query: str)`
- 可执行任意 SQL 语句
- 对 `SHOW TABLES` 做了专门输出格式处理
- 对返回结果集的查询,统一转为 `header + rows` 的 CSV 文本
- 对非查询语句(INSERT/UPDATE/DELETE 等),返回“受影响行数”说明
> 在生产环境中建议对 `execute_sql` 做一定限制(例如:只允许 SELECT),
> 以避免通过 LLM 误删 / 误改数据。
---
## 测试
目前提供了一个简单的单元测试文件:`tests/test_server.py`:
- 验证 `app` 实例是否正确创建
- 验证缺少关键环境变量时,`get_db_config` 会抛出 `ValueError`
运行测试:```bash
# 确保已安装开发依赖
uv pip install -r requirements-dev.txt
# 运行所有测试
pytest
> 当前测试不依赖真实 MySQL,适合作为“快速回归”。
> 如果你想做集成测试,可以参考原来的 conftest.py 思路,
> 启动一个测试数据库,创建临时表,再调用资源/工具进行验证。
安全建议
访问数据库本身就有一定风险,建议遵循以下原则:
- 为 MCP Server 创建一个权限受限的专用数据库用户(不要使用 root)
- 仅授予必要的权限(例如:只读环境只给
SELECT) - 对生产库要格外谨慎,可以只连从库或备份库
- 对
execute_sql工具在服务端做白名单 / 黑名单限制
本仓库还提供了 SECURITY.md,里面有比较详细的 MySQL 权限管理建议,
例如:如何创建只读用户、如何限制权限、如何审计访问等,建议在生产前认真阅读。
目录结构(关键部分)```text
src/
mysql_mcp_server/
init.py # 导出 app 和 main,供命令行脚本使用
server.py # FastMCP 服务器核心逻辑(大量中文注释,适合学习)
tests/
test_server.py # 基础单元测试示例
pyproject.toml # 项目配置(依赖、脚本入口等)
requirements.txt # 运行时依赖
requirements-dev.txt # 开发 / 测试依赖
smithery.yaml # Smithery 启动配置(uvx + 环境变量)
Dockerfile # 使用 Docker 部署时可选(不再强制依赖)
SECURITY.md # MySQL 权限与安全配置建议
```
