MCP Server for MySQL

基于 NodeJS 的 MySQL MCP 服务器

提供对 MySQL 数据库的只读访问的模型上下文协议 (MCP) 服务器。该服务器使 LLM 能够检查数据库架构并执行只读查询。

安装

使用 Smithery

安装和配置此 MCP 服务器的最简单方法是通过Smithery ：

在配置过程中，系统会提示您输入 MySQL 连接详细信息。Smithery 将自动执行以下操作：

• 设置正确的环境变量
• 配置你的 LLM 应用程序以使用 MCP 服务器
• 测试与 MySQL 数据库的连接
• 如果需要，提供有用的故障排除

使用 MCP 获取

您也可以使用MCP Get安装此软件包：

MCP Get 提供 MCP 服务器的集中注册并简化安装过程。

使用 NPM/PNPM

对于手动安装：

手动安装后，您需要配置您的 LLM 应用程序以使用 MCP 服务器（请参阅下面的配置部分）。

成分

工具

• mysql_query
  • 对连接的数据库执行只读 SQL 查询
  • 输入： sql （字符串）：要执行的 SQL 查询
  • 所有查询都在只读事务中执行
  • 支持准备好的语句以进行安全参数处理
  • 可配置查询超时和结果分页
  • 内置查询执行统计信息

资源

服务器提供全面的数据库信息：

• 表模式
  • 每个表的 JSON 架构信息
  • 列名和数据类型
  • 索引信息和约束
  • 外键关系
  • 表统计数据和指标
  • 从数据库元数据中自动发现

安全功能

• 通过准备好的语句预防 SQL 注入
• 查询白名单/黑名单功能
• 查询执行的速率限制
• 查询复杂度分析
• 可配置的连接加密
• 只读事务执行

性能优化

• 优化连接池
• 查询结果缓存
• 大型结果集流
• 查询执行计划分析
• 可配置查询超时

监控和调试

• 全面的查询日志记录
• 性能指标收集
• 错误跟踪和报告
• 健康检查端点
• 查询执行统计信息

配置

使用 Smithery 自动配置

如果您使用 Smithery 安装，则您的配置已设置完毕。您可以使用以下命令查看或修改它：

Claude 桌面应用程序的手动配置

要为 Claude 桌面应用程序手动配置 MCP 服务器，请将以下内容添加到您的claude_desktop_config.json文件（通常位于您的用户目录中）：

将db_name替换为您的数据库名称或将其留空以访问所有数据库。

高级配置选项

为了更好地控制 MCP 服务器的行为，您可以使用以下高级配置选项：

环境变量

基本连接

• MYSQL_HOST ：MySQL 服务器主机（默认值：“127.0.0.1”）
• MYSQL_PORT ：MySQL 服务器端口（默认值：“3306”）
• MYSQL_USER ：MySQL 用户名（默认值：“root”）
• MYSQL_PASS ：MySQL 密码
• MYSQL_DB ：目标数据库名称

性能配置

• MYSQL_POOL_SIZE ：连接池大小（默认值：“10”）
• MYSQL_QUERY_TIMEOUT ：查询超时（以毫秒为单位）（默认值：“30000”）
• MYSQL_CACHE_TTL ：缓存生存时间（以毫秒为单位）（默认值：“60000”）

安全配置

• MYSQL_RATE_LIMIT ：每分钟最大查询数（默认值：“100”）
• MYSQL_MAX_QUERY_COMPLEXITY ：最大查询复杂度分数（默认值：“1000”）
• MYSQL_SSL ：启用 SSL/TLS 加密（默认值：“false”）

监控配置

• MYSQL_ENABLE_LOGGING ：启用查询日志记录（默认值：“false”）
• MYSQL_LOG_LEVEL ：日志记录级别（默认值：“info”）
• MYSQL_METRICS_ENABLED ：启用性能指标（默认值：“false”）

测试

数据库设置

在运行测试之前，您需要设置测试数据库并用测试数据填充它：

1. 创建测试数据库和用户
   -- Connect as root and create test database CREATE DATABASE IF NOT EXISTS mcp_test; -- Create test user with appropriate permissions CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password'; GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost'; FLUSH PRIVILEGES;
2. 运行数据库设置脚本
   # Run the database setup script pnpm run setup:test:db
   这将创建必要的表和种子数据。脚本位于scripts/setup-test-db.ts
3. 配置测试环境在项目根目录中创建一个.env.test文件：
   MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=mcp_test MYSQL_PASS=mcp_test_password MYSQL_DB=mcp_test
4. 更新 package.json 脚本将这些脚本添加到您的 package.json：
   { "scripts": { "setup:test:db": "ts-node scripts/setup-test-db.ts", "pretest": "pnpm run setup:test:db", "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage" } }

运行测试

该项目包括一个全面的测试套件，以确保功能性和可靠性：

故障排除

使用 Smithery 进行故障排除

如果您安装了 Smithery，则可以使用其内置诊断程序：

使用 MCP Get 进行故障排除

如果您使用 MCP Get 安装：

常见问题

1. 连接问题
   • 验证 MySQL 服务器是否正在运行并且可以访问
   • 检查凭证和权限
   • 如果启用，请确保 SSL/TLS 配置正确
   • 尝试连接 MySQL 客户端以确认访问
2. 性能问题
   • 调整连接池大小
   • 配置查询超时值
   • 如果需要，启用查询缓存
   • 检查查询复杂性设置
   • 监控服务器资源使用情况
3. 安全限制
   • 检查速率限制配置
   • 检查查询白名单/黑名单设置
   • 验证 SSL/TLS 设置
   • 确保用户具有适当的 MySQL 权限
4. 路径解析如果遇到错误“无法连接到 MCP 服务器 mcp-server-mysql”，请明确设置所有必需二进制文件的路径：

5. 身份验证问题
   • 对于 MySQL 8.0+，确保服务器支持caching_sha2_password身份验证插件
   • 检查你的 MySQL 用户是否配置了正确的身份验证方法
   • 如果需要，请尝试创建具有传统身份验证的用户：
     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

贡献

欢迎贡献！请随时向https://github.com/benborla/mcp-server-mysql提交 Pull 请求。

开发设置

1. 克隆存储库
2. 安装依赖项： pnpm install
3. 构建项目： pnpm run build
4. 运行测试： pnpm test

项目路线图

我们正在积极改进此 MCP 服务器。查看我们的CHANGELOG.md了解计划推出的功能详情，包括：

• 使用准备好的语句增强查询功能
• 高级安全功能
• 性能优化
• 全面监控
• 扩展架构信息

如果您想为这些领域做出贡献，请查看 GitHub 上的问题或打开一个新问题来讨论您的想法。

提交更改

1. 分叉存储库
2. 创建功能分支： git checkout -b feature/your-feature-name
3. 提交您的更改： git commit -am 'Add some feature'
4. 推送到分支： git push origin feature/your-feature-name
5. 提交拉取请求

执照

此 MCP 服务器采用 MIT 许可证。详情请参阅许可证文件。