基于NodeJS的MySQL MCP服务器
提供MySQL数据库访问的模型上下文协议服务器。此服务器使LLM能够检查数据库模式并执行SQL查询。
目录
- 克劳德桌面 - 光标 - 史密瑟里 - MCP获取 - 克隆到本地存储库
需求
- Node.js v18或更高版本
- MySQL 5.7或更高版本（推荐MySQL 8.0+）
- MySQL用户，具有所需操作的适当权限
- 对于写操作：具有INSERT、UPDATE和/或DELETE权限的MySQL用户
安装
安装和配置MCP服务器有几种方法：
克劳德桌面
要为Claude Desktop App手动配置MCP服务器，请将以下内容添加到您的 claude_desktop_config.json 文件（通常位于您的用户目录中）：
{
"mcpServers": {
"mcp_server_mysql": {
"command": "npx",
"args": [
"-y",
"@benborla29/mcp-server-mysql"
],
"env": {
"MYSQL_HOST": "127.0.0.1",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASS": "your_password",
"MYSQL_DB": "your_database",
"ALLOW_INSERT_OPERATION": "false",
"ALLOW_UPDATE_OPERATION": "false",
"ALLOW_DELETE_OPERATION": "false",
"PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path
"NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"`
}
}
}
}光标
对于Cursor IDE，您可以在项目中使用以下命令安装此MCP服务器：
npx mcprunner MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASS=root MYSQL_DB=demostore ALLOW_INSERT_OPERATION=true ALLOW_UPDATE_OPERATION=true ALLOW_DELETE_OPERATION=false -- npx -y @benborla29/mcp-server-mysql别忘了更换 env 该命令上的值。如果你有最新版本的Cursor（v0.47及以上版本），只需复制并粘贴下面的配置：
mcp.json
{
"mcpServers": {
"MySQL": {
"command": "npx",
"args": [
"mcprunner",
"MYSQL_HOST=127.0.0.1",
"MYSQL_PORT=3306",
"MYSQL_USER=root",
"MYSQL_PASS=root",
"MYSQL_DB=demostore",
"ALLOW_INSERT_OPERATION=true",
"ALLOW_UPDATE_OPERATION=true",
"ALLOW_DELETE_OPERATION=false",
"--",
"npx",
"-y",
"@benborla29/mcp-server-mysql"
]
}
}
}使用Smithery
安装和配置此MCP服务器的最简单方法是通过 史密瑟里:
npx -y @smithery/cli@latest install @benborla29/mcp-server-mysql --client claude在配置过程中，系统会提示您输入MySQL连接详细信息。Smithery将自动：
- 设置正确的环境变量
- 配置LLM应用程序以使用MCP服务器
- 测试与MySQL数据库的连接
- 如果需要，提供有帮助的故障排除
- 配置写入操作设置（INSERT、UPDATE、DELETE权限）
安装程序将要求提供以下连接详细信息：
- MySQL主机（默认值：127.0.0.1）
- MySQL端口（默认：3306）
- MySQL用户名
- MySQL密码
- MySQL数据库名称
- SSL配置（如果需要）
- 写入操作权限：
- 允许INSERT操作（默认值：false） - 允许UPDATE操作（默认值：false） - 允许DELETE操作（默认值：false）
出于安全原因，默认情况下禁用写入操作。仅当您需要Claude修改数据库数据时才启用它们。
使用MCP Get
您还可以使用安装此软件包 MCP获取:
npx @michaellatman/mcp-get@latest install @benborla29/mcp-server-mysqlMCP Get提供了MCP服务器的集中式注册表，简化了安装过程。
使用NPM/PNPM
对于手动安装：
# Using npm
npm install -g @benborla29/mcp-server-mysql
# Using pnpm
pnpm add -g @benborla29/mcp-server-mysql手动安装后，您需要配置LLM应用程序以使用MCP服务器（请参阅下面的配置部分）。
从本地存储库运行
如果要直接从源代码克隆并运行此MCP服务器，请执行以下步骤：
- 克隆存储库
git clone https://github.com/benborla/mcp-server-mysql.git
cd mcp-server-mysql- 安装依赖项
npm install
# or
pnpm install- 构建项目
npm run build
# or
pnpm run build- 配置Claude桌面
将以下内容添加到您的Claude Desktop配置文件中(claude_desktop_config.json):
{
"mcpServers": {
"mcp_server_mysql": {
"command": "/path/to/node",
"args": [
"/full/path/to/mcp-server-mysql/dist/index.js"
],
"env": {
"MYSQL_HOST": "127.0.0.1",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASS": "your_password",
"MYSQL_DB": "your_database",
"ALLOW_INSERT_OPERATION": "false",
"ALLOW_UPDATE_OPERATION": "false",
"ALLOW_DELETE_OPERATION": "false",
"PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path
"NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"`
}
}
}
}替换：
- /path/to/node 带有Node.js二进制文件的完整路径（使用 which node) - /full/path/to/mcp-server-mysql 包含克隆存储库的完整路径 - 设置MySQL凭据以匹配您的环境
- 测试服务器
# Run the server directly to test
node dist/index.js如果它成功连接到MySQL，您就可以将其与Claude Desktop一起使用了。
组件
工具
- mysql_query
- 对连接的数据库执行SQL查询 - 输入： sql （string）：要执行的SQL查询 - 默认情况下，仅限于只读操作 - 可选写入操作（通过配置启用时）： - INSERT：向表中添加新数据（需要 ALLOW_INSERT_OPERATION=true) - 更新：修改现有数据（需要 ALLOW_UPDATE_OPERATION=true) - DELETE：删除数据（需要 ALLOW_DELETE_OPERATION=true) - 所有操作都在具有适当提交/回滚处理的事务中执行 - 支持用于安全参数处理的准备语句 - 可配置的查询超时和结果分页 - 内置查询执行统计
资源
服务器提供全面的数据库信息：
- 持微软签名的表模式
- 每个表的JSON模式信息 - 列名和数据类型 - 索引信息和约束 - 外键关系 - 表统计和指标 - 从数据库元数据中自动发现
安全功能
- 通过预处理语句防止SQL注入
- 查询白名单/黑名单功能
- 查询执行的速率限制
- 查询复杂性分析
- 可配置的连接加密
- 只读事务执行
性能优化
- 优化连接池
- 查询结果缓存
- 大型结果集流
- 查询执行计划分析
- 可配置的查询超时
监控与调试
- 全面的查询日志记录
- 绩效指标收集
- 错误跟踪和报告
- 健康检查端点
- 查询执行统计
配置
Smithery自动配置
如果您是使用Smithery安装的，那么您的配置已经设置好了。您可以通过以下方式查看或修改它：
smithery configure @benborla29/mcp-server-mysql重新配置时，您可以更新任何MySQL连接详细信息以及写入操作设置：
- 基本连接设置:
- MySQL主机、端口、用户、密码、数据库 - SSL/TLS配置（如果您的数据库需要安全连接）
- 写入操作权限:
- 允许INSERT操作：如果要允许添加新数据，请设置为true - 允许更新操作：如果要允许更新现有数据，请设置为true - 允许删除操作：如果要允许删除数据，请设置为true
出于安全原因，默认情况下禁用所有写入操作。仅当您特别需要Claude修改数据库数据时，才启用这些设置。
高级配置选项
为了更好地控制MCP服务器的行为，您可以使用以下高级配置选项：
{
"mcpServers": {
"mcp_server_mysql": {
"command": "/path/to/npx/binary/npx",
"args": [
"-y",
"@benborla29/mcp-server-mysql"
],
"env": {
// Basic connection settings
"MYSQL_HOST": "127.0.0.1",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASS": "",
"MYSQL_DB": "db_name",
"PATH": "/path/to/node/bin:/usr/bin:/bin",
// Performance settings
"MYSQL_POOL_SIZE": "10",
"MYSQL_QUERY_TIMEOUT": "30000",
"MYSQL_CACHE_TTL": "60000",
// Security settings
"MYSQL_RATE_LIMIT": "100",
"MYSQL_MAX_QUERY_COMPLEXITY": "1000",
"MYSQL_SSL": "true",
// Monitoring settings
"MYSQL_ENABLE_LOGGING": "true",
"MYSQL_LOG_LEVEL": "info",
"MYSQL_METRICS_ENABLED": "true",
// Write operation flags
"ALLOW_INSERT_OPERATION": "false",
"ALLOW_UPDATE_OPERATION": "false",
"ALLOW_DELETE_OPERATION": "false"
}
}
}
}环境变量
基本连接
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”）ALLOW_INSERT_OPERATION：启用INSERT操作（默认值：“false”）ALLOW_UPDATE_OPERATION：启用UPDATE操作（默认值：“false”）ALLOW_DELETE_OPERATION：启用DELETE操作（默认值：“false”）ALLOW_DDL_OPERATION：启用DDL操作（默认值：“false”）SCHEMA_INSERT_PERMISSIONS：特定于架构的INSERT权限SCHEMA_UPDATE_PERMISSIONS：特定于架构的UPDATE权限SCHEMA_DELETE_PERMISSIONS：特定于架构的DELETE权限SCHEMA_DDL_PERMISSIONS：特定于架构的DDL权限MULTI_DB_WRITE_MODE：在多数据库模式下启用写入操作（默认值：“false”）
监控配置
MYSQL_ENABLE_LOGGING：启用查询日志记录（默认值：“false”）MYSQL_LOG_LEVEL：日志记录级别（默认值：“info”）MYSQL_METRICS_ENABLED：启用性能指标（默认值：“false”）
多数据库模式
MCP Server MySQL支持在没有设置特定数据库的情况下连接到多个数据库。这允许LLM查询MySQL用户可以访问的任何数据库。有关完整详细信息，请参阅 README-MULTI-DB.md.
启用多数据库模式
要启用多数据库模式，只需离开 MYSQL_DB 环境变量为空。在多数据库模式下，查询需要模式限定：
-- Use fully qualified table names
SELECT * FROM database_name.table_name;
-- Or use USE statements to switch between databases
USE database_name;
SELECT * FROM table_name;架构特定权限
为了对数据库操作进行细粒度控制，MCP Server MySQL现在支持特定于模式的权限。这允许不同的数据库具有不同的访问级别（只读、读写等）。
配置示例
SCHEMA_INSERT_PERMISSIONS=development:true,test:true,production:false
SCHEMA_UPDATE_PERMISSIONS=development:true,test:true,production:false
SCHEMA_DELETE_PERMISSIONS=development:false,test:true,production:false
SCHEMA_DDL_PERMISSIONS=development:false,test:true,production:false有关完整的详细信息和安全建议，请参阅 README-MULTI-DB.md.
测试
数据库设置
在运行测试之前，您需要设置测试数据库并为其添加测试数据种子：
- 创建测试数据库和用户
-- 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;- 运行数据库安装脚本
# Run the database setup script
pnpm run setup:test:db这将创建必要的表和种子数据。脚本位于 scripts/setup-test-db.ts
- 配置测试环境
创建一个 .env.test 项目根目录中的文件（如果不存在）：
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=mcp_test
MYSQL_PASS=mcp_test_password
MYSQL_DB=mcp_test- 更新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"
}
}运行测试
该项目包括一个全面的测试套件，以确保功能和可靠性：
# First-time setup
pnpm run setup:test:db
# Run all tests
pnpm test故障排除
常见问题
- 连接问题
- 验证MySQL服务器是否正在运行且可访问 - 检查凭据和权限 - 如果启用，请确保SSL/TLS配置正确 - 尝试连接MySQL客户端以确认访问
- 性能问题
- 调整连接池大小 - 配置查询超时值 - 如果需要，启用查询缓存 - 检查查询复杂性设置 - 监控服务器资源使用情况
- 安全限制
- 审查限速配置 - 检查查询白名单/黑名单设置 - 验证SSL/TLS设置 - 确保用户具有适当的MySQL权限
- 路径解析
如果遇到错误“无法连接到MCP服务器MCP-server mysql”，请显式设置所有必需二进制文件的路径：
{
"env": {
"PATH": "/path/to/node/bin:/usr/bin:/bin"
}
}*我在哪里可以找到我的 node 料箱路径* 运行以下命令以获取它：
对于 路径
echo "$(which node)/../" 对于 节点路径
echo "$(which node)/../../lib/node_modules" - Claude桌面特定问题
- 如果您在Claude Desktop中看到“服务器已断开连接”日志，请检查以下日志 ~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log - 确保您使用的是Node二进制文件和服务器脚本的绝对路径 - 检查你的 .env 文件已正确加载；在配置中使用显式环境变量 - 尝试直接从命令行运行服务器，查看是否存在连接问题 - 如果需要写操作（INSERT、UPDATE、DELETE），请在配置中将相应的标志设置为“true”：
"env": {
"ALLOW_INSERT_OPERATION": "true", // Enable INSERT operations
"ALLOW_UPDATE_OPERATION": "true", // Enable UPDATE operations
"ALLOW_DELETE_OPERATION": "true" // Enable DELETE operations
}- 确保你的MySQL用户对你正在启用的操作拥有适当的权限 - 对于直接执行配置，请使用：
{
"mcpServers": {
"mcp_server_mysql": {
"command": "/full/path/to/node",
"args": [
"/full/path/to/mcp-server-mysql/dist/index.js"
],
"env": {
"MYSQL_HOST": "127.0.0.1",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASS": "your_password",
"MYSQL_DB": "your_database"
}
}
}
}- 身份验证问题
- 对于MySQL 8.0+，确保服务器支持 caching_sha2_password 身份验证插件 - 检查MySQL用户是否配置了正确的身份验证方法 - 如果需要，请尝试使用传统身份验证创建用户：
CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';@李庄
- 我遇到了
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from错误
尝试以下解决方法：
npx -y -p @benborla29/mcp-server-mysql -p dotenv mcp-server-mysql感谢@lizhuangs
贡献
欢迎投稿！请随时向提交拉取请求 https://github.com/benborla/mcp-server-mysql
开发设置
- 克隆存储库
- 安装依赖项：
pnpm install - 构建项目：
pnpm run build - 运行测试：
pnpm test
项目路线图
我们正在积极致力于增强此MCP服务器。查看我们的 更改日志.md 有关计划功能的详细信息，包括：
- 通过预处理语句增强查询功能
- 高级安全功能
- 性能优化
- 综合监控
- 扩展的架构信息
如果你想为这些领域做出贡献，请查看GitHub上的问题或打开一个新的问题来讨论你的想法。
提交变化
- 分叉存储库
- 创建要素分支：
git checkout -b feature/your-feature-name - 提交您的更改：
git commit -am 'Add some feature' - 推到分支：
git push origin feature/your-feature-name - 提交拉取请求
许可证
此MCP服务器根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。