使用说明

MySQL MCP服务器

Rust中的高性能MySQL模型上下文协议（MCP）服务器实现，支持具有安全、基于密钥的访问控制的多个数据源。

特性

多数据源支持：同时连接到多个MySQL服务器
基于密钥的安全访问：使用安全密钥访问数据库，而不是公开凭据
连接池：通过可配置的池设置进行高效的连接管理
流媒体支持：使用内存高效的流式处理大型结果集
综合工具：查询执行、模式检查、数据库列表等
MCP资源：通过标准化的资源URI浏览数据库元数据
错误恢复：使用指数回退和重新连接自动重试
监控：实时连接池统计和结构化日志记录

安装

先决条件

锈1.70或更高版本
MySQL 5.7或更高版本（或MariaDB 10.2+）

从源头构建

git clone https://github.com/yourusername/mysql-mcp-rust.git
cd mysql-mcp-rust
cargo build --release

编译后的二进制文件将在 target/release/mysql-mcp-rust.

配置

配置文件

服务器使用TOML配置文件来定义数据源和服务器设置。创建一个 config.toml 基于提供的文件 config.example.toml:

cp config.example.toml config.toml

重要：添加 config.toml 到你的 .gitignore 为了避免提交敏感凭据：

echo "config.toml" >> .gitignore

配置结构

全局设置

# Query timeout in seconds (default: 30)
query_timeout_secs = 30

# Stream chunk size in rows (default: 1000)
stream_chunk_size = 1000

数据源配置

每个数据源都需要以下字段：

[[data_sources]]
key = "prod-db-01"              # Unique identifier (required)
name = "Production Database"    # Human-readable name (required)
host = "localhost"              # MySQL host (required)
port = 3306                     # MySQL port (required)
username = "root"               # MySQL username (required)
password = "password"           # MySQL password (required)
databases = []                  # Allowed databases (empty = all)

[data_sources.pool_config]
max_connections = 10            # Maximum pool connections
min_connections = 2             # Minimum pool connections
connection_timeout_secs = 30    # Connection timeout
idle_timeout_secs = 300         # Idle connection timeout
max_lifetime_secs = 1800        # Maximum connection lifetime

环境变量

为了安全起见，建议将密码存储在环境变量中：

[[data_sources]]
key = "prod-db-01"
name = "Production Database"
host = "localhost"
port = 3306
username = "root"
password = "$MYSQL_PASSWORD"    # Loads from environment variable
databases = []

在启动服务器之前设置环境变量：

export MYSQL_PASSWORD="your_secure_password"
./target/release/mysql-mcp-rust

有关环境变量的详细信息，请参见环境变量指南.

数据库访问控制

通过在列表中列出特定数据库来限制对它们的访问 databases 数组：

[[data_sources]]
key = "dev-db-01"
name = "Development Database"
host = "localhost"
port = 3306
username = "dev_user"
password = "$DEV_PASSWORD"
databases = ["test_db", "dev_db"]  # Only these databases are accessible

离开 databases 数组为空，允许访问服务器上的所有数据库。

用法

启动服务器

# Using default config file (config.toml in current directory)
./target/release/mysql-mcp-rust

# Using custom config file via environment variable
MCP_CONFIG_PATH=/path/to/config.toml ./target/release/mysql-mcp-rust

服务器使用MCP协议通过stdio进行通信。

快速开始

创建配置文件：
```
cp config.example.toml config.toml
```
将数据库密码设置为环境变量：
```
export MYSQL_PASSWORD="your_password"
```
编辑config.toml 以匹配MySQL服务器设置
启动服务器：
```
./target/release/mysql-mcp-rust
```
测试连接 使用MCP客户端

与MCP客户端集成

服务器可以与任何兼容MCP的客户端集成。以下是常见客户端的示例配置：

克劳德桌面版

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "mysql": {
      "command": "/path/to/mysql-mcp-rust",
      "env": {
        "MCP_CONFIG_PATH": "/path/to/config.toml",
        "MYSQL_PASSWORD": "your_password"
      }
    }
  }
}

通用MCP客户端

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: '/path/to/mysql-mcp-rust',
  env: {
    MCP_CONFIG_PATH: '/path/to/config.toml',
    MYSQL_PASSWORD: 'your_password'
  }
});

const client = new Client({
  name: 'mysql-client',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

可用工具

服务器提供以下MCP工具：

1. `mysql_query`

执行SQL查询并检索结果。

参数：

datasource_key （字符串，必填）：数据源标识符
database （字符串，必填）：数据库名称
query （字符串，必填）：SQL查询语句
stream （布尔值，可选）：启用大型结果的流式传输

例子：

{
  "datasource_key": "prod-db-01",
  "database": "users",
  "query": "SELECT * FROM accounts WHERE status = 'active' LIMIT 10"
}

2. `mysql_execute`

执行DML语句（INSERT、UPDATE、DELETE）。

参数：

datasource_key （字符串，必填）：数据源标识符
database （字符串，必填）：数据库名称
statement （字符串，必填）：SQL语句

退货：

affected_rows：受影响的行数
last_insert_id：最后插入的ID（用于INSERT语句）

例子：

{
  "datasource_key": "prod-db-01",
  "database": "users",
  "statement": "UPDATE accounts SET status = 'inactive' WHERE last_login < '2023-01-01'"
}

3. `mysql_list_datasources`

列出所有已配置的数据源。

参数： 无

退货： 包含键、名称和状态的数据源数组。

4. `mysql_list_databases`

列出数据源的所有数据库。

参数：

datasource_key （字符串，必填）：数据源标识符

退货： 包含元数据（大小、字符集、排序规则）的数据库数组。

5. `mysql_list_tables`

列出数据库中的所有表。

参数：

datasource_key （字符串，必填）：数据源标识符
database （字符串，必填）：数据库名称

退货： 包含元数据（行数、大小、引擎）的表数组。

6. `mysql_describe_table`

获取详细的表格结构。

参数：

datasource_key （字符串，必填）：数据源标识符
database （字符串，必填）：数据库名称
table （字符串，必填）：表名

退货： 表架构，包括列、主键、外键和索引。

7. `mysql_get_connection_stats`

获取连接池统计信息。

参数：

datasource_key （字符串，可选）：特定数据源（全部省略）

退货： 连接池统计信息（活动、空闲、总连接数、排队请求）。

MCP资源

通过资源URI访问数据库元数据：

mysql://datasources -列出所有数据源
mysql://{key}/databases -列出数据源的数据库
mysql://{key}/{database}/tables -列出数据库中的表
mysql://{key}/{database}/tables/{table} -获取表架构
mysql://{key}/{database}/schema -获取完整的数据库架构

安全

基于密钥的访问

服务器使用基于密钥的访问模型，其中：

数据源在服务器启动时配置了凭据
客户端使用数据源密钥访问数据库
实际凭据永远不会通过MCP协议公开
所有错误消息都经过清理，以删除凭据信息

最佳实践

使用环境变量：将密码存储在环境变量中，而不是配置文件中
限制数据库访问：使用 databases 数组以限制对特定数据库的访问
连接限制：为您的工作负载配置适当的连接池限制
查询超时：设置合理的查询超时以防止长时间运行的查询
监控：定期检查连接池统计数据和日志

错误处理

服务器实现了全面的错误处理：

连接失败：自动重试，指数回退（最多3次尝试）
查询超时：超过30秒的查询将自动终止
无效请求：清除无效参数或SQL的错误消息
资源耗竭：巧妙地处理连接池限制
自动恢复：不可用数据源的后台重新连接

监控和日志记录

结构化日志记录

服务器使用以下级别的结构化日志记录：

错误：需要注意的关键错误
警告：警告条件
信息：一般信息性消息
调试：详细的调试信息
追踪：非常详细的跟踪信息

连接池统计信息

连接池统计信息每60秒记录一次，包括：

活动连接
空闲连接
总连接数
排队请求

使用访问实时统计数据 mysql_get_connection_stats 工具。

性能调整

连接池配置

根据您的工作负载调整池设置：

[data_sources.pool_config]
max_connections = 20        # Increase for high concurrency
min_connections = 5         # Keep warm connections ready
connection_timeout_secs = 60    # Increase for slow networks
idle_timeout_secs = 600     # Adjust based on connection cost
max_lifetime_secs = 3600    # Rotate connections periodically

查询优化

使用 stream 大型结果集的参数
调整 stream_chunk_size 基于内存约束
设置适当 query_timeout_secs 对于您的疑问

缓存

服务器实现智能缓存：

数据库列表：60秒
模式信息：5分钟（可配置）

故障排除

连接问题

问题：无法连接到MySQL服务器

解决方案:

验证主机和端口是否正确
检查MySQL服务器是否正在运行且可访问
验证用户名和密码
检查防火墙规则
查看MySQL用户权限

未找到环境变量

问题: Environment variable 'VAR_NAME' not found

解决方案：在启动服务器之前设置环境变量：

export VAR_NAME="value"

配置验证错误

问题：配置验证失败

解决方案:

确保所有必填字段都存在（密钥、名称、主机、端口、用户名、密码）
检查重复的数据源密钥
验证端口号是否有效（>0）
确保min_connections≤max_connections

查询超时

问题：查询超时

解决方案:

增加 query_timeout_secs 在配置中
优化慢速查询
添加适当的索引
对大型结果集使用流式传输

权限不足

问题：MySQL用户缺少必要的权限

解决方案:

为MySQL用户授予适当的权限
对于只读访问： GRANT SELECT ON database.* TO 'user'@'host';
对于读写访问： GRANT SELECT, INSERT, UPDATE, DELETE ON database.* TO 'user'@'host';
刷新权限： FLUSH PRIVILEGES;

发展

运行测试

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run with logging
RUST_LOG=debug cargo test

基于属性的测试

该项目包括基于性能的综合测试，使用 proptest:

# Run property tests
cargo test --test '*_property_test'

项目信息

版本: 0.1.0
语言：铁锈（2021年版）
MCP协议：使用 rmcp 图书馆
数据库驱动: sqlx 支持MySQL
异步运行时东京：

许可证

[您的许可证在这里]

贡献

欢迎投稿！请随时提交拉取请求。

开发设置

克隆仓库
安装Rust（1.70或更高版本）
安装MySQL进行测试
运行测试： cargo test
构建： cargo build

运行测试

# Run all tests
cargo test

# Run unit tests only
cargo test --lib

# Run integration tests
cargo test --test '*'

# Run property-based tests
cargo test --test '*_property_test'

# Run with logging
RUST_LOG=debug cargo test

文档

快速参考 -常见操作的快速参考
配置指南 -详细的配置选项和示例
环境变量指南 -管理密码和敏感数据
使用示例 -使用所有工具和功能的实际示例
实施总结 -每个组件的技术实施细节

支持

对于问题和疑问：

GitHub问题：[您的存储库URL]
文档：[您的文档URL]

使用说明

MySQL MCP服务器

特性

安装

先决条件

从源头构建

配置

配置文件

配置结构

全局设置

数据源配置

环境变量

数据库访问控制

用法

启动服务器

快速开始

与MCP客户端集成

克劳德桌面版

通用MCP客户端

可用工具

1. mysql_query

2. mysql_execute

3. mysql_list_datasources

4. mysql_list_databases

5. mysql_list_tables

6. mysql_describe_table

7. mysql_get_connection_stats

MCP资源

安全

基于密钥的访问

最佳实践

错误处理

监控和日志记录

结构化日志记录

连接池统计信息

性能调整

连接池配置

查询优化

缓存

故障排除

连接问题

未找到环境变量

配置验证错误

查询超时

权限不足

发展

运行测试

基于属性的测试

项目信息

许可证

贡献

开发设置

运行测试

文档

支持

相关 MCP

Windows自动化MCP服务器

Proxmox VE 管理服务

MySQL协议服务器

KSM MCP服务器

文件系统访问服务

数据安全访问与智能查询服务

1. `mysql_query`

2. `mysql_execute`

3. `mysql_list_datasources`

4. `mysql_list_databases`

5. `mysql_list_tables`

6. `mysql_describe_table`

7. `mysql_get_connection_stats`