mysql

MySQL MCP 服务

面向 MySQL 数据库的高质量 Model Context Protocol（MCP）服务实现。此服务可让 Claude 等 AI 助手通过标准化协议与 MySQL 数据库交互。

版本：0.2.0 | 协议：MCP 2025-03-26 | Rust：1.70+ | 状态：已可用于生产环境

目录

• 功能
• 安装
• 快速开始（5 分钟）
• 使用方法
• 可用工具
• 数据库上下文功能
• 安全注意事项
• 架构
• 故障排除
• 开发
• 部署指南
• 贡献
• 许可证
• 支持

功能

• 架构检查：获取表架构和结构信息
• 查询执行：执行 SQL 查询（为确保安全，默认仅允许读取）
• 数据操作：插入、更新和删除操作
• 数据库上下文：为每个查询指定要使用的数据库
• 安全控制：可配置查询限制，防止危险操作
• 连接管理：稳健的连接处理机制，支持重试逻辑和连接池
• 错误处理：全面的错误报告，并提供详细信息
• JSON-RPC 2.0 协议：通过 stdio 实现标准化通信

安装

前置条件

• Rust 1.70+
• MySQL 5.7+ 或 MariaDB 10.2+
• 可访问 MySQL 数据库

从源代码构建

git clone <repository-url>
cd mcp-server-mysql
cargo build --release

编译后的二进制文件位于 target/release/mcp-server-mysql。

从发行包安装

# Extract the package
tar -xzf mcp-server-mysql-v0.2.0-linux-x86_64.tar.gz

# Move binary to system path (optional)
sudo cp mcp-server-mysql /usr/local/bin/

# Verify installation
mcp-server-mysql --version

快速开始（5 分钟）

第 1 步：构建服务

cargo build --release

二进制文件位于 target/release/mcp-server-mysql。

第 2 步：测试连接

./target/release/mcp-server-mysql \
  --host localhost \
  --username root \
  --password yourpassword \
  --database testdb

你应该会看到：“MCP MySQL Server started and ready to accept connections”

第 3 步：配置 Claude Desktop

编辑 Claude Desktop 配置文件：

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

添加以下配置：

{
  "mcpServers": {
    "mysql": {
      "command": "/absolute/path/to/mcp-server-mysql",
      "args": [
        "--host", "localhost",
        "--port", "3306",
        "--username", "your_username",
        "--password", "your_password",
        "--database", "your_database"
      ]
    }
  }
}

安全提示：在生产环境中，请考虑使用环境变量或安全的机密管理解决方案，而不要在配置文件中硬编码密码。

第 4 步：重启 Claude Desktop

完全关闭并重新打开 Claude Desktop。你应该会看到一个小锤子图标，表示 MCP 服务已连接。

第 5 步：试用！

向 Claude 提问：

• “你能展示我的 MySQL 数据库中 users 表的架构吗？”
• “查询数据库，展示 products 表中前 10 行”
• “我的数据库中有哪些表？”

使用方法

命令行参数

mcp-server-mysql \
  --host localhost \
  --port 3306 \
  --username your_username \
  --password your_password \
  --database your_database \
  --allow-dangerous-queries false

参数参考

参数	说明	默认值	必需
--host	MySQL 服务主机名	localhost	否
--port	MySQL 服务端口	3306	否
--username	MySQL 用户名	-	是
--password	MySQL 密码	（空）	否
--database	要连接的数据库名称	-	是
--allow-dangerous-queries	允许 INSERT/UPDATE/DELETE 查询	false	否

使用 Claude Desktop 进行配置

将以下配置添加到 Claude Desktop 配置文件中：

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

{
  "mcpServers": {
    "mysql": {
      "command": "/path/to/mcp-server-mysql",
      "args": [
        "--host", "localhost",
        "--port", "3306",
        "--username", "your_username",
        "--password", "your_password",
        "--database", "your_database"
      ]
    }
  }
}

可用工具

1. mysql（架构检查）

获取数据库表的架构信息。

参数：

• table_name（字符串）：要检查的表名；或使用 "all-tables" 获取所有表的架构

示例：

{
  "table_name": "users"
}

返回：

• 列信息（名称、类型、是否可为空、默认值、键）
• 索引信息
• 表约束

2. query（SQL 执行）

在数据库上执行 SQL 查询。

参数：

• query（string）：要执行的 SQL 查询
• database（string，可选）：此查询要使用的数据库名称

示例：

{
  "query": "SELECT * FROM users WHERE active = 1 LIMIT 10",
  "database": "my_database"
}

安全性：

• 默认情况下，仅允许 SELECT 查询
• 使用 --allow-dangerous-queries 标志启用 INSERT/UPDATE/DELETE
• 除非明确启用，否则会阻止危险关键字

3. insert（插入数据）

向指定表中插入数据。

参数：

• table_name（string）：表名
• data（object）：列名和值的键值对

示例：

{
  "table_name": "users",
  "data": {
    "username": "john_doe",
    "email": "[email protected]",
    "active": true
  }
}

**返回：**最后一次插入的 ID

4. update（更新数据）

根据条件更新指定表中的数据。

参数：

• table_name（string）：表名
• data（object）：要更新的列及其值的键值对
• conditions（object）：WHERE 子句的键值对

示例：

{
  "table_name": "users",
  "data": {
    "email": "[email protected]",
    "updated_at": "2024-01-15 10:30:00"
  },
  "conditions": {
    "id": 123
  }
}

**返回：**受影响的行数

5. delete（删除数据）

根据条件删除指定表中的数据。

参数：

• table_name（string）：表名
• conditions（object）：WHERE 子句的键值对

示例：

{
  "table_name": "users",
  "conditions": {
    "id": 123
  }
}

**返回：**受影响的行数

**警告：**请务必指定条件，以免删除所有行！

数据库上下文功能

问题

此前，查询之间不会保留数据库上下文：

-- Query 1
USE dev_database;  -- Succeeds

-- Query 2 (new connection from pool)
SELECT * FROM my_table;  -- ❌ Fails: context was lost

解决方案

在每次查询中使用可选的 database 参数：

{
  "query": "SELECT * FROM my_table",
  "database": "dev_database"
}

优点

1. 明确清晰：准确了解每次查询使用的数据库
2. 没有隐藏状态：每次查询彼此独立
3. 向后兼容：不带参数的现有查询仍可正常工作
4. 没有竞态条件：每次查询都会获得自己的连接
5. 简单易用：只需在查询参数中添加 "database": "name"

使用示例

使用数据库参数的基本查询

{
  "query": "SELECT * FROM crm_sites LIMIT 10",
  "database": "dev_smartConnect_za"
}

不带数据库参数的查询（使用默认数据库）

{
  "query": "SELECT * FROM users WHERE active = 1"
}

使用 --database 启动参数指定的数据库。

在同一会话中使用多个数据库

// Query database 1
{
  "query": "SELECT COUNT(*) FROM customers",
  "database": "production_db"
}

// Query database 2
{
  "query": "SELECT COUNT(*) FROM test_data",
  "database": "test_db"
}

前后对比

之前（必须使用完全限定名称）：

SELECT * FROM dev_smartConnect_za.crm_sites
  JOIN dev_smartConnect_za.crm_orgs ON ...
WHERE dev_smartConnect_za.crm_sites.active = 1;

之后（简洁明了）：

{
  "query": "SELECT * FROM crm_sites JOIN crm_orgs ON ... WHERE active = 1",
  "database": "dev_smartConnect_za"
}

常见场景

场景 1：单数据库项目

设置默认数据库并省略该参数：

# Startup
--database my_project_db

# Query (no database parameter needed)
{
  "query": "SELECT * FROM users"
}

场景 2：多数据库项目

为每次查询指定数据库：

// Customer database
{ "query": "...", "database": "customers_db" }

// Orders database
{ "query": "...", "database": "orders_db" }

// Analytics database
{ "query": "...", "database": "analytics_db" }

错误处理

错误代码 -32005：连接获取失败

Cause: Connection pool exhausted
Solution: Retry after a moment

错误代码 -32006：数据库上下文切换失败

Cause: Database doesn't exist or user lacks permissions
Solution: Verify database exists and user has access

最佳实践

✅ 建议

• 为生产查询明确指定数据库
• 在查询中使用描述性数据库名称
• 使用 SELECT DATABASE() 验证上下文
• 按数据库分组查询，以便于查看

❌ 不建议

• 在同一查询中混用限定名称和非限定名称
• 假设上下文会持续保留——请为每次查询指定数据库
• 尽可能避免在数据库名称中使用特殊字符
• 忘记验证用户对所有数据库的权限

安全注意事项

只读模式（默认）

默认情况下，服务以只读模式运行，仅允许 SELECT 查询。这可以防止意外修改或删除数据。

危险查询模式

使用 --allow-dangerous-queries 启用写入操作：

mcp-server-mysql --username user --password pass --database mydb --allow-dangerous-queries true

**请谨慎使用！**启用后可执行：

• INSERT 语句
• UPDATE 语句
• DELETE 语句
• 其他可能造成破坏的操作

SQL 注入防护

• 表名经过验证，仅允许包含字母数字字符和下划线
• 所有数据值均通过预处理语句进行参数化
• 通过将反引号替换为两个反引号来转义数据库名称
• 不会进行原始 SQL 字符串拼接

连接安全

• 支持标准的 MySQL SSL/TLS 连接
• 可安全配置连接字符串
• 可通过环境变量提供密码
• 建议使用权限受限的专用数据库用户

生产环境部署安全

1. 使用专用数据库用户：

   CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'secure_password';
   GRANT SELECT ON your_database.* TO 'mcp_user'@'localhost';
   FLUSH PRIVILEGES;
   

2. 仅在需要时启用写入权限：

   --allow-dangerous-queries true  # Use with caution!
   

3. 使用环境变量（未来增强）： 可考虑用 shell 脚本包装二进制文件，以便从环境变量读取配置。

架构

系统概览

┌─────────────────────────────────────────────────────┐
│           MCP Client (e.g., Claude)                 │
│  Sends: {query, database}                           │
└────────────────────────┬────────────────────────────┘
                         │ JSON-RPC 2.0 (stdio)
                         ▼
┌─────────────────────────────────────────────────────┐
│      MCP MySQL Server (Rust)                        │
│                                                      │
│  execute_query(query, database, pool)               │
│  ├─ If database param:                              │
│  │  ├─ Acquire connection from pool                 │
│  │  ├─ Execute: USE `database`                      │
│  │  └─ Execute: [user's query]                      │
│  └─ Else:                                           │
│     └─ Execute query on pool (default database)     │
└────────────────────────┬────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│      MySQL Connection Pool (5 connections)          │
└────────────────────────┬────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│      MySQL/MariaDB Server                           │
└─────────────────────────────────────────────────────┘

使用数据库参数查询的序列

Client          MCP Server       Connection Pool      MySQL Server
  │                 │                    │                  │
  │  query +        │                    │                  │
  │  database       │                    │                  │
  ├────────────────>│                    │                  │
  │                 │                    │                  │
  │                 │ acquire()          │                  │
  │                 ├───────────────────>│                  │
  │                 │ <connection>       │                  │
  │                 │<───────────────────┤                  │
  │                 │                    │                  │
  │                 │ USE database       │                  │
  │                 ├────────────────────┼─────────────────>│
  │                 │ OK                 │                  │
  │                 │<────────────────────┼──────────────────┤
  │                 │                    │                  │
  │                 │ SELECT query       │                  │
  │                 ├────────────────────┼─────────────────>│
  │                 │ Results            │                  │
  │                 │<────────────────────┼──────────────────┤
  │                 │                    │                  │
  │                 │ release()          │                  │
  │                 ├───────────────────>│                  │
  │  Results        │                    │                  │
  │<────────────────┤                    │                  │

连接池管理

Pool (5 connections)
┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐
│ C1 │ │ C2 │ │ C3 │ │ C4 │ │ C5 │
└────┘ └────┘ └────┘ └────┘ └────┘

Key Properties:
• Each query gets its own connection instance
• Database context is set per connection, per query
• No state persists between queries
• Fully thread-safe and concurrent

技术细节

• 协议版本：MCP 2025-03-26
• 传输方式：stdio（JSON-RPC 2.0）
• 连接池：最多 5 个连接
• 重试逻辑：发生暂时性故障时自动重新连接
• 性能开销：使用数据库参数时，每次查询约为 50-200 微秒

故障排查

连接失败

如果遇到连接错误：

1. 检查 MySQL 是否正在运行：

   mysql -h localhost -u your_username -p
   

2. 验证凭据：

   • 确保用户名和密码正确
   • 确认用户有权访问指定数据库

3. 检查网络访问：

   • 验证主机和端口是否正确
   • 确保防火墙未阻止连接

4. 查看服务日志：

   • 服务会将日志写入 stderr
   • 查看详细错误消息

常见错误

“Database connection failed”

• MySQL 服务可能未运行
• 主机或端口配置不正确
• 网络连接问题

“Only SELECT queries are allowed”

• 你正在只读模式下尝试执行写入查询
• 如果需要写入权限，请添加 --allow-dangerous-queries true

“No database selected”

• 指定的数据库不存在
• 用户无权访问该数据库
• 执行 SHOW DATABASES; 查看可用数据库

“Table doesn't exist”

• 确认查询的是正确的数据库
• 如果使用多个数据库，请添加 database 参数
• 使用 SELECT DATABASE() 检查当前上下文

“Failed to acquire connection”

• 连接池已耗尽
• 稍等片刻后重试

Claude Desktop 中未显示工具

1. 确认二进制文件的路径是绝对路径（而不是相对路径）
2. 检查 Claude Desktop 日志中是否有错误
3. 完全重启 Claude Desktop（而不只是重新加载）
4. 确保手动运行时服务进程能够正常启动

开发

项目结构

mcp-server-mysql/
├── src/
│   ├── main.rs          # Main server implementation
│   ├── config.rs        # Configuration handling
│   ├── db.rs            # Database operations
│   ├── rpc.rs           # RPC protocol handling
│   └── server.rs        # Server initialization
├── tests/               # Test files
├── Cargo.toml           # Rust dependencies
├── Cargo.lock          # Locked dependency versions
└── README.md           # This file

开发构建

cargo build
cargo run -- --help

运行测试

cargo test

代码质量

# Format code
cargo fmt

# Run linter
cargo clippy

# Check for issues
cargo check

开发约定

项目遵循 Rust 标准最佳实践：

• 代码格式化：cargo fmt
• 代码检查：cargo clippy
• 测试：cargo test

部署指南

快速部署

1. 测试连接

./mcp-server-mysql \
  --username your_user \
  --password your_pass \
  --database your_db

看到“已启动 MCP MySQL 服务”后，按 Ctrl+C 退出。

2. 配置 Claude Desktop

编辑 Claude 配置文件并添加服务配置（请参阅“快速开始”部分）。

3. 重启 Claude Desktop

完全关闭并重新打开 Claude Desktop。

生产环境部署提示

性能

• 使用 --release 标志优化二进制文件
• 已配置连接池（最多 5 个连接）
• 暂时性故障时会自动重试

监控

服务日志会写入 stderr。使用以下方式捕获日志：

./mcp-server-mysql --username user --password pass --database db 2>> server.log

日志级别：

• INFO：连接事件、工具调用
• DEBUG：详细的查询信息
• WARN：非致命问题
• ERROR：故障和错误

Systemd 服务（可选）

对于长时间运行的部署，请创建 /etc/systemd/system/mcp-mysql.service：

[Unit]
Description=MySQL MCP Server
After=network.target mysql.service

[Service]
Type=simple
User=mcp-user
ExecStart=/usr/local/bin/mcp-server-mysql --username mcp_user --password secret --database production
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

启用并启动：

sudo systemctl enable mcp-mysql
sudo systemctl start mcp-mysql
sudo systemctl status mcp-mysql

升级

# Backup current version
cp /usr/local/bin/mcp-server-mysql /usr/local/bin/mcp-server-mysql.backup

# Replace with new version
cp mcp-server-mysql /usr/local/bin/

# Restart services
sudo systemctl restart mcp-mysql  # If using systemd
# Or restart Claude Desktop

回滚

# Restore previous version
cp /usr/local/bin/mcp-server-mysql.backup /usr/local/bin/mcp-server-mysql

# Or checkout previous git tag
git checkout v0.1.0
cargo build --release

贡献

欢迎贡献！请确保：

• 代码遵循 Rust 最佳实践
• 所有测试均通过
• 文档已更新
• 提交消息清晰且描述准确

许可证

Apache-2.0

支持

如有问题、疑问或想要贡献，请在项目仓库中提交 issue。

---

版本：0.2.0 | 发布日期：2025-01-XX | 协议：MCP 2025-03-26 | 平台：Linux x86_64 | 状态：已可用于生产环境 ✅