MySQL MCP 服务器

一个用于MySQL数据库操作的模型上下文协议（MCP）服务器，基于Anthropic的MCP软件开发工具包（SDK）构建。设计旨在与Claude Code及其他MCP客户端实现无缝集成。

特点/功能

核心工具

🔧 修理工具/螺丝刀 13 MCP 工具：

- 基础： query， list_databases， list_tables， describe_table - 性能分析： explain_query， show_indexes， get_table_stats - 数据管理： export_data (JSON/CSV)， create_backup (mysqldump) - 模式检查： get_foreign_keys， get_database_schema （附带美人鱼风格的ER图） - 管理: show_processlist， kill_query

能力

🔒 表示“锁定”或“安全”的符号。 权限控制可配置的只读、写入和删除权限
🪵 木头 会话日志记录带有会话管理的自动查询日志记录
⚡（闪电符号，常用于表示速度、活力、电能等概念，在此无具体文字对应，可保持原样或根据上下文意译为“闪电”、“极速”等） 使用MCP SDK构建使用官方Anthropic MCP SDK
🎯（靶心，目标） 数据库过滤限制对特定数据库的访问
⏱️（时钟） 查询超时保护可配置的连接和查询超时时间
📈 表示“上升趋势”或“增长”的图表符号。 性能分析解释查询计划、索引检查、表统计信息
💾 保存（电脑图标） 数据导出将查询结果导出为JSON或CSV格式
🗂️（文件夹图标，可理解为“文件夹”或“分类”） 模式可视化带有Mermaid ER图的完整数据库模式
🛠️（扳手） 数据库管理进程监控和查询终止

快速入门（长文略）

⚡ 一键安装

选项1：全局安装（单一配置）

# Install with UV - works for all projects
claude mcp add mysql-mcp -s user -- uv run --directory /path/to/myql_mcp_sever python src/main.py

选项2：按项目设置并使用环境变量（推荐）

# No need for separate config files! Use environment variables
# In Project A directory
claude mcp add mysql -s project -e MYSQL_DATABASE=project_a_db -- uv run --directory /path/to/myql_mcp_sever python src/main.py

# In Project B directory
claude mcp add mysql -s project -e MYSQL_DATABASE=project_b_db -- uv run --directory /path/to/myql_mcp_sever python src/main.py

选项3：单独配置文件（传统方式）

# Create config.ec-site.toml with specific settings
claude mcp add mysql-ec-site -s user -- uv run --directory /path/to/myql_mcp_sever python src/main.py config.ec-site.toml

先决条件

# Install UV (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies (one-time setup)
cd /Users/kietnguyen/projects/myql-mcp
uv sync

为什么选择UV（紫外线）？ ⚡

UV 是一个极快的 Python 包管理器（比 pip 快 10-100 倍）：

快速安装并行下载和安装软件包
锁文件： uv.lock 确保安装可重复
集成的与……配合使用 pyproject.toml 标准
兼容的用于替换pip/venv的即插即用解决方案

安装： curl -LsSf https://astral.sh/uv/install.sh | sh

详细设置

1. 安装依赖项

选项A：使用紫外线（⚡ 推荐）

# Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies from pyproject.toml + uv.lock
uv sync

# Or just install without dev dependencies
uv sync --no-dev

选项B：使用pip（传统方式）

pip3 install -r requirements.txt

紫外线益处：

🚀 比 pip 快 10 到 100 倍
🔒 用于可重复构建的锁定文件（uv.lock）
📦 更好的依赖解析
🎯 集成于 pyproject.toml

2. 配置MySQL连接

选项A：简单单一数据库（默认）

复制并编辑 config.toml:

cp config.example.toml config.toml
vim config.toml

[mysql]
host = "localhost"
port = 3306
user = "root"
password = "your_password"
connection_timeout = 10
query_timeout = 30

[permissions]
allow_write = false  # Enable INSERT, UPDATE
allow_delete = false # Enable DELETE
allowed_databases = []  # Empty = all databases allowed

选项B：项目特定配置

对于特定的项目/数据库：

cp configs/project-specific.toml config.myproject.toml
vim config.myproject.toml

[mysql]
host = "localhost"
port = 3306
user = "project_user"
password = "project_password"

[permissions]
allowed_databases = ["my_project_db"]  # Only this database
allow_write = false

选项C：多个环境

开发/预生产/生产环境的设置：

# Development
cp configs/development.toml config.dev.toml

# Production (read-only)
cp configs/production.toml config.prod.toml

添加每个环境：

# Dev environment
claude mcp add mysql-dev --scope local -- uv run --directory $(pwd) python src/main.py config.dev.toml

# Prod environment (read-only)
claude mcp add mysql-prod --scope user -- uv run --directory $(pwd) python src/main.py config.prod.toml

见 \configs/README.md\ 翻译成中文为：\配置文件/README.md\ 或 \配置/README.md\（具体翻译可能根据上下文有所调整，但基本意思是指位于“configs”目录下的“README.md”文件）查看更多配置示例！

3. 运行服务器（测试）

带紫外线：

# Run with UV (uses pyproject.toml dependencies)
uv run python src/main.py

# Or with custom config
uv run python src/main.py /path/to/config.toml

使用Python：

python3 src/main.py

# Or with custom config
python3 src/main.py /path/to/config.toml

4. 配置Claude代码

你有 两个选项 配置MCP服务器：

选项A：使用带有UV的CLI（⚡ 推荐）

# Add MCP server using UV runtime
claude mcp add mysql-mcp \
  --scope user \
  --transport stdio \
  -- uv run --directory /absolute/path/to/myql-mcp python src/main.py

为什么要使用 uv run？

自动使用正确的Python版本
从（指定位置）加载依赖项 pyproject.toml
隔离环境
无需激活虚拟环境

选项A2：使用Python的CLI（传统方式）

# Add MCP server using direct Python
claude mcp add mysql-mcp \
  --scope user \
  --transport stdio \
  -- python3 /absolute/path/to/myql-mcp/src/main.py

CLI 选项：

--scope配置范围

- local - 仅当前目录（建议用于测试） - user - 您用户的所有项目（~/.claude/config.json） - project - 具体项目（在项目根目录下的.mcp.json文件）

--transport连接类型（默认：stdio）

- stdio - 标准输入/输出（用于本地Python/Node服务器） - sse - 服务器发送事件（用于远程服务器） - http - HTTP REST API

--env设置环境变量（例如。， -e DB_PASSWORD=secret）

常用命令：

# List all configured MCP servers
claude mcp list

# Get details about a specific server
claude mcp get mysql

# Remove a server
claude mcp remove mysql

# Add with environment variables
claude mcp add mysql \
  --scope user \
  --env MYSQL_HOST=localhost \
  --env MYSQL_PORT=3306 \
  -- python /absolute/path/to/myql-mcp/src/main.py

选项B：手动JSON配置

在您的Claude代码MCP设置中添加：

用户范围： ~/.claude/config.json
项目范围： .mcp.json 在项目根目录下

{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["/absolute/path/to/myql-mcp/src/main.py"],
      "cwd": "/absolute/path/to/myql-mcp"
    }
  }
}

使用环境变量：

{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["/absolute/path/to/myql-mcp/src/main.py"],
      "cwd": "/absolute/path/to/myql-mcp",
      "env": {
        "CUSTOM_CONFIG": "/path/to/custom/config.toml"
      }
    }
  }
}

5. 验证安装

# List configured servers
claude mcp list

# Should show:
# mysql (stdio) - /path/to/myql-mcp/src/main.py

# Test the server manually
python src/main.py
# Should see: 🚀 MySQL MCP Server starting...
#             📊 Session ID: YYYYMMDD_HHMMSS

使用示例

在Claude代码中使用

配置完成后，您可以在Claude代码中直接使用MCP工具：

示例1：列出所有数据库

Hey Claude, can you list all available MySQL databases?

示例2：显示数据库中的表

Show me all tables in the ec-site database

示例3：查询数据

Can you query the first 10 users from the ec_accounts table in ec-site database?

示例4：描述表结构

What's the structure of the mgmt_department table in ec-site?

示例5：复杂查询

Run this query on ec-site:
SELECT a.id, a.email, c.site_kbn
FROM ec_accounts a
INNER JOIN ec_account_configs c ON a.id = c.account_id
WHERE a.is_deleted = 0
LIMIT 5

示例6：性能分析（新增）

This query seems slow. Can you analyze it with EXPLAIN?
SELECT * FROM orders WHERE customer_email LIKE '%gmail%'

示例7：检查索引（新增）

Show me all indexes on the users table in ec-site database

示例8：表统计（新增）

How big is the orders table? Show me the statistics

示例9：导出数据

Export the first 100 active users to CSV format
SELECT id, email, created_at FROM users WHERE status = 'active' LIMIT 100

示例10：获取数据库模式

Show me the complete schema for the ec-site database with an ER diagram

示例11：监控正在运行的查询

What queries are currently running on the database?

示例12：终止一个慢查询

Kill process ID 12345

可用工具

1. `query`

在MySQL数据库上执行SQL查询。

参数：

sql （必填）：要执行的SQL语句
database （可选）：数据库名称

示例：

{
  "sql": "SELECT * FROM users LIMIT 10",
  "database": "ec-site"
}

2. `list_databases`

列出所有可用的MySQL数据库。

参数： 无

返回值： 数据库名称数组

3. `list_tables`

列出特定数据库中的所有表。

参数：

database （必填）：数据库名称

返回值： 表名数组

4. `describe_table`

描述表格的结构。

参数：

database （必填）：数据库名称
table （必填）：表名

返回值： 列定义数组

5. `explain_query` （新增 - 性能分析）

使用 MySQL EXPLAIN 分析 SQL 查询执行计划。

参数：

sql （必需）：用于分析的SQL SELECT语句
database （可选）：数据库名称

示例：

{
  "sql": "SELECT * FROM users WHERE email LIKE '%@gmail.com'",
  "database": "ec-site"
}

返回值：

执行计划详情（表访问类型、键使用情况）
性能警告（全表扫描、文件排序、临时表）
索引使用建议

用例：

在慢查询引起问题之前识别它们
查找缺失的索引
优化复杂的JOIN查询

6. `show_indexes` (新增 - 索引检查)

显示表的所有索引。

参数：

database （必填）：数据库名称
table （必填）：表名

示例：

{
  "database": "ec-site",
  "table": "users"
}

返回值：

索引名称和类型（BTREE，HASH）
唯一索引与非唯一索引
柱的组成和序列
校对信息

用例：

在查询前验证索引是否存在
理解复合指数的排序
检查查询的索引覆盖情况

7. `get_table_stats` （新增 - 表统计）

获取全面的表格统计信息和元数据。

参数：

database （必填）：数据库名称
table （必填）：表名

示例：

{
  "database": "ec-site",
  "table": "orders"
}

返回值：

准确的行数统计（通过 SELECT COUNT(\*)）
数据大小和索引大小（人类可读格式）
存储引擎（InnoDB、MyISAM 等）
自增值
校对
创建/更新的时间戳

用例：

监控表格增长
能力规划（或容量规划）
数据库健康检查
优化前/后的对比

8. `export_data` （新增 - 数据导出）

将查询结果导出为JSON或CSV格式。

参数：

sql （必需）：要执行的 SQL SELECT 语句
format （可选）：输出格式 - “json”或“csv”（默认：”json”）
database （可选）：数据库名称
limit （可选）：要导出的最大行数

示例（JSON）：

{
  "sql": "SELECT * FROM products WHERE category = 'electronics'",
  "format": "json",
  "database": "ec-site",
  "limit": 1000
}

示例（CSV）：

{
  "sql": "SELECT id, name, price FROM products",
  "format": "csv",
  "database": "ec-site"
}

返回值： 格式化后的数据已准备好进行文件导出或分析

用例：

提取数据以用于报告
为特定数据集创建备份
导出至Excel/电子表格进行分析
与团队分享查询结果

9. `get_foreign_keys` (模式检查)

获取表的外键关系。

参数：

database （必填）：数据库名称
table （必填）：表名

示例：

{
  "database": "ec-site",
  "table": "orders"
}

返回值：

外键约束名称
源列和引用列
引用的表格
在更新/删除规则时

用例：

理解表之间的关系
规划数据迁移
验证引用完整性
文档数据库结构

10. `show_processlist` （行政管理）

显示当前正在运行的MySQL进程和查询。

参数：

full （可选）：显示完整查询文本（默认：否）

示例：

{
  "full": true
}

返回：

进程ID，用户，主机，数据库
查询文本和执行时间
进程状态
性能警告（长时间查询、锁）

用例：

监控数据库活动
识别慢查询
检测被锁定的资源
调试性能问题

11. `create_backup` (数据管理)

使用mysqldump创建SQL备份。

参数：

database （必填）：数据库名称
tables （可选）：表名列表（默认：所有表）
include_data （可选）：包含 INSERT 语句（默认：true）

示例：

{
  "database": "ec-site",
  "tables": ["users", "orders"],
  "include_data": true
}

返回值：

SQL 备份文本
备份大小和统计信息

用例：

创建数据库备份
仅导出模式（不包含数据：false）
备份特定表
数据库迁移准备

12. `get_database_schema` (模式可视化)

获取包含所有关系的完整数据库模式。

参数：

database （必填）：数据库名称
format （可选）：输出格式 - “json”或“mermaid”（默认：json）

示例：

{
  "database": "ec-site",
  "format": "mermaid"
}

返回值：

所有包含列和数据类型的表
外键关系
每个表的索引
美人鱼ER图（如果格式为：“mermaid”）

用例：

可视化数据库结构
生成实体关系图（ER图）
文档数据库架构
计划模式变更

13. `kill_query` （行政）

终止正在运行的 MySQL 查询或连接。

参数：

process_id （必需）：来自 SHOW PROCESSLIST 的进程 ID

示例：

{
  "process_id": 12345
}

返回：

成功状态
查询信息已终止
用户和主机详情

用例：

阻止失控查询
释放被锁定的资源
应急数据库管理
性能故障排除

MCP配置范围

理解三种配置范围：

1. 局部范围（`--scope local`）

位置仅当前目录
配置文件： ./.mcp.json
最适合用于测试，项目特定的覆盖设置
示例：

  # Only works when you're in this directory
  cd /path/to/project
  claude mcp add mysql --scope local -- python ./src/main.py

2. 用户范围（`--scope user`\[推荐\]

位置用户的主目录
配置文件: ~/.claude/config.json
最适合于你在所有项目中使用的个人工具
示例：

  # Works everywhere for this user
  claude mcp add mysql --scope user -- python /absolute/path/to/myql-mcp/src/main.py

3. 项目范围（`--scope project`)

位置项目根目录
配置文件： ./.mcp.json
最适合于共享团队配置
示例:

  # Team can commit .mcp.json to git
  cd /path/to/team-project
  claude mcp add mysql --scope project -- python /shared/path/to/myql-mcp/src/main.py

建议使用 user 为个人MySQL MCP服务器提供便携性，以便随时随地可用，或者 project 带有环境变量的范围，用于项目级别的数据库隔离。

配置参考

环境变量覆盖

v0.1.0 新增功能你可以使用环境变量覆盖任何配置值，从而允许使用单一的 config.toml 为多个项目提供服务！

支持的环境变量：

# MySQL Connection
MYSQL_HOST=localhost              # Override MySQL host
MYSQL_PORT=3306                   # Override MySQL port
MYSQL_USER=root                   # Override MySQL user
MYSQL_PASSWORD=secret             # Override MySQL password
MYSQL_CONNECTION_TIMEOUT=10       # Connection timeout (seconds)
MYSQL_QUERY_TIMEOUT=30            # Query timeout (seconds)

# Database Access Control
MYSQL_DATABASE=myproject_db       # Restrict to specific database (adds to allowed_databases)

# Permissions
MYSQL_ALLOW_WRITE=true           # Allow INSERT, UPDATE (true/false/1/0/yes/no)
MYSQL_ALLOW_DELETE=false         # Allow DELETE, DROP, TRUNCATE

示例：无需多个配置文件的多项目设置

# Base config.toml has your MySQL credentials
# Each project adds its own database restriction via env var

# Project A
cd /path/to/project-a
claude mcp add mysql -s project -e MYSQL_DATABASE=project_a_db -- uv run --directory /path/to/myql_mcp_sever python src/main.py

# Project B
cd /path/to/project-b
claude mcp add mysql -s project -e MYSQL_DATABASE=project_b_db -- uv run --directory /path/to/myql_mcp_sever python src/main.py

MySQL 配置

[mysql]
host = "localhost"          # MySQL server host
port = 3306                 # MySQL server port
user = "root"               # MySQL username
password = "password"       # MySQL password
connection_timeout = 10     # Connection timeout (seconds)
query_timeout = 30          # Query execution timeout (seconds)

权限

[permissions]
allow_write = false         # Allow INSERT, UPDATE operations
allow_delete = false        # Allow DELETE, DROP, TRUNCATE operations
allowed_databases = []      # List of allowed databases (empty = all)
enabled_tools = [           # List of enabled MCP tools
    "query",
    "list_databases",
    "list_tables",
    "describe_table",
    "explain_query",
    "show_indexes",
    "get_table_stats",
    "export_data",
    "get_foreign_keys",
    "show_processlist",
    "create_backup",
    "get_database_schema",
    "kill_query"
]

记录日志

[logging]
enabled = true              # Enable logging
log_queries = true          # Log SQL queries
log_results = true          # Log query results
log_errors = true           # Log errors
log_dir = "./logs"          # Log directory

项目结构

myql-mcp/
├── config.toml                 # Configuration file
├── pyproject.toml              # UV project config
├── requirements.txt            # Python dependencies
├── README.md                   # This file
│
├── src/
│   ├── main.py                # Entry point
│   └── mysql_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server implementation
│       ├── config.py          # Configuration loader
│       ├── database.py        # MySQL connection & queries
│       ├── tools.py           # MCP tools implementation
│       └── logger.py          # Session logging
│
└── logs/                       # Session logs (auto-created)

安全特性

默认只读除非明确启用，否则写操作被禁用
数据库白名单限制对特定数据库的访问
查询超时防止长时间运行的查询
SQL注入防护在适用的情况下使用参数化查询
工具过滤启用/禁用特定工具
安全查询终止在终止查询前验证进程ID

会话管理

会话开始当MCP服务器启动时（当Claude Code连接时）
会话结束当MCP服务器停止时（当Claude Code断开连接时）
自动清理会话结束时，日志会被清除
会话ID基于时间戳的唯一标识符
查询日志记录所有操作均记录了持续时间和结果

故障排除

连接被拒绝

验证MySQL服务器是否正在运行
检查MySQL凭据 config.toml
确保MySQL端口可访问

权限被拒绝

检查 allowed_databases 在 config.toml
验证 allow_write 和 allow_delete 设置
确保MySQL用户拥有所需的权限

工具不可用

检查 enabled_tools 列表中的 config.toml
配置更改后重启MCP服务器

MCP服务器未在Claude代码中显示

# Check if server is configured
claude mcp list

# If not listed, add it again
claude mcp add mysql --scope user -- python /absolute/path/to/myql-mcp/src/main.py

# Get details about the server
claude mcp get mysql

服务器启动失败

# Test server manually first
cd /Users/kietnguyen/projects/myql-mcp
python src/main.py

# Check for errors in output
# Common issues:
# - MySQL connection failed → Check config.toml credentials
# - Module not found → Run: uv sync

错误的Python版本

# MCP might use different Python than expected
# Specify full path to Python:
claude mcp add mysql --scope user -- /usr/bin/python3 /absolute/path/to/myql-mcp/src/main.py

# Or use virtual environment Python:
claude mcp add mysql --scope user -- /path/to/venv/bin/python /absolute/path/to/myql-mcp/src/main.py

环境变量未生效

# Use --env flag to pass environment variables
claude mcp add mysql \
  --scope user \
  --env MYSQL_HOST=192.168.1.100 \
  --env MYSQL_PORT=3307 \
  -- python /absolute/path/to/myql-mcp/src/main.py

发展

安装开发依赖项

pip install -r requirements.txt

运行测试（如已实现）

pytest

代码格式化

black src/
ruff check src/

许可证

MIT 许可证 - 欢迎根据需要自由使用和修改。

致谢/鸣谢

构建于：

______________________________________________________________________

查询愉快！ 🚀

myql MCP sever

快速接入

详细介绍

MySQL MCP 服务器

特点/功能

核心工具

能力

快速入门（长文略）

⚡ 一键安装

先决条件

为什么选择UV（紫外线）？ ⚡

详细设置

1. 安装依赖项

选项A：使用紫外线（⚡ 推荐）

选项B：使用pip（传统方式）

2. 配置MySQL连接

选项A：简单单一数据库（默认）

选项B：项目特定配置

选项C：多个环境

3. 运行服务器（测试）

带紫外线：

使用Python：

4. 配置Claude代码

选项A：使用带有UV的CLI（⚡ 推荐）

选项A2：使用Python的CLI（传统方式）

选项B：手动JSON配置

5. 验证安装

使用示例

在Claude代码中使用

可用工具

1. query

2. list_databases

3. list_tables

4. describe_table

5. explain_query （新增 - 性能分析）

6. show_indexes (新增 - 索引检查)

7. get_table_stats （新增 - 表统计）

8. export_data （新增 - 数据导出）

9. get_foreign_keys (模式检查)

10. show_processlist （行政管理）

11. create_backup (数据管理)

12. get_database_schema (模式可视化)

13. kill_query （行政）

MCP配置范围

1. 局部范围（--scope local）

2. 用户范围（--scope user\[推荐\]

3. 项目范围（--scope project)

配置参考

环境变量覆盖

MySQL 配置

权限

记录日志

项目结构

安全特性

会话管理

故障排除

连接被拒绝

权限被拒绝

工具不可用

MCP服务器未在Claude代码中显示

服务器启动失败

错误的Python版本

环境变量未生效

发展

安装开发依赖项

运行测试（如已实现）

代码格式化

许可证

致谢/鸣谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `query`

2. `list_databases`

3. `list_tables`

4. `describe_table`

5. `explain_query` （新增 - 性能分析）

6. `show_indexes` (新增 - 索引检查)

7. `get_table_stats` （新增 - 表统计）

8. `export_data` （新增 - 数据导出）

9. `get_foreign_keys` (模式检查)

10. `show_processlist` （行政管理）

11. `create_backup` (数据管理)

12. `get_database_schema` (模式可视化)

13. `kill_query` （行政）

1. 局部范围（`--scope local`）

2. 用户范围（`--scope user`\[推荐\]

3. 项目范围（`--scope project`)