AI导哈

MySQL安全操作服务器

一个为MySQL数据库操作提供安全控制和操作限制的模型上下文协议（MCP）服务器，适用于与Claude Code、Codex CLI等MCP兼容的AI助手集成。

  • by thebusted
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 thebusted/mcp-mysql-server

使用说明

MCP MySQL 服务器

一个用于MySQL数据库操作的模型上下文协议（MCP）服务器，内置安全功能和操作抗干扰能力。非常适合与Claude Code、Codex CLI以及其他MCP兼容的AI助手一起使用。

特点/特性

  • 安全的MySQL操作自由执行SELECT查询，同时控制破坏性操作
  • **“Operation Resistance”可以翻译为“抵抗行动”**可配置的INSERT、UPDATE和DELETE限制
  • 模式保护DROP、TRUNCATE 和 ALTER 操作始终被阻止
  • 防止SQL注入使用带参数绑定的预编译语句
  • 多种工具查询执行、表列表查看、模式检查和数据库信息查询
  • 连接池高效的连接管理以提升性能
  • 详细的错误报告带有SQL代码的清晰错误信息

快速入门

选项1：自动设置（最简单）

# One command - does everything!
./setup.sh

该脚本将：

  • 自动检测 Bun 或 npm
  • 安装依赖项
  • 创建并可选配置 .env 文件
  • 构建项目
  • 测试数据库连接

选项2：手动设置

使用 Bun（更快）：

bun install
cp .env.example .env && nano .env
bun run build

使用 npm：

npm install
cp .env.example .env && nano .env
npm run build

集成指南

配置

环境变量

创建一个 .env 文件（使用 .env.example （作为模板）：

# MySQL Connection
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=your_username
MYSQL_PASS=your_password
MYSQL_DB=your_database

# Operation Permissions (true/false)
ALLOW_INSERT_OPERATION=false
ALLOW_UPDATE_OPERATION=false
ALLOW_DELETE_OPERATION=false

MCP客户端配置

对于Claude Code，请添加到您的 ~/.config/claude-code/.mcp.json：

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASS": "your_password",
        "MYSQL_DB": "your_database",
        "ALLOW_INSERT_OPERATION": "false",
        "ALLOW_UPDATE_OPERATION": "false",
        "ALLOW_DELETE_OPERATION": "false"
      }
    }
  }
}

需要更多例子吗？ 见 docs/mcp-config-examples.md 翻译为中文是：“文档/mcp配置示例.md” 对于：

  • 多个数据库
  • 远程/Docker 配置
  • 开发环境与生产环境设置
  • 特定于平台的路径

查看 集成指南 以获取详细的设置说明。

安全特性

总是阻塞操作

这些操作是 总是被阻挡 无论配置如何：

  • DROP - 删除表/数据库
  • TRUNCATE - 截断表（或清空表）
  • ALTER - 修改表结构

可配置操作

通过环境变量控制这些操作：

  • INSERT - 由……控制 ALLOW_INSERT_OPERATION
  • UPDATE - 由……控制 ALLOW_UPDATE_OPERATION
  • DELETE - 由……控制 ALLOW_DELETE_OPERATION

始终允许的操作

  • SELECT - 阅读数据总是被允许的

可用工具

1. mysql_query（在MySQL中用于执行SQL查询的函数）

执行带有安全限制的SQL查询。

参数：

  • query (字符串，必需): 要执行的SQL查询
  • params (数组，可选)：预编译语句的参数

示例：

{
  "query": "SELECT * FROM users WHERE id = ?",
  "params": [123]
}

回答：

{
  "success": true,
  "rows": [...],
  "rowCount": 5,
  "fields": [...]
}

2. mysql_list_tables（MySQL列出表）

列出当前数据库中的所有表。

示例回复：

{
  "success": true,
  "tables": [
    { "Tables_in_db": "users" },
    { "Tables_in_db": "products" }
  ]
}

3. mysql描述表（或 mysql表描述）

获取特定表的结构/模式。

参数：

  • table (字符串，必填)：表名

示例回复：

{
  "success": true,
  "table": "users",
  "columns": [
    {
      "Field": "id",
      "Type": "int",
      "Null": "NO",
      "Key": "PRI",
      "Default": null,
      "Extra": "auto_increment"
    }
  ]
}

4. 获取MySQL数据库信息

获取数据库连接和权限的相关信息。

示例回复：

{
  "success": true,
  "connection": {
    "host": "localhost",
    "port": 3306,
    "user": "tommygun",
    "database": "db"
  },
  "permissions": {
    "INSERT": false,
    "UPDATE": false,
    "DELETE": false,
    "SELECT": true,
    "DROP": false,
    "TRUNCATE": false,
    "ALTER": false
  }
}

使用示例

如需全面示例，请参阅 示例/使用示例.md。

快速示例

安全的SELECT查询：

Get the first 10 users from the database

参数化查询（防止SQL注入）：

Find products where category is 'electronics' and price is less than 1000

数据分析：

Show me monthly revenue for the last 6 months

模式探索：

What tables are in my database?
Show me the structure of the users table

阻塞操作

当操作被禁用时，您会收到明确的错误信息：

{
  "error": "INSERT operations are disabled. Set ALLOW_INSERT_OPERATION=true to enable.",
  "blocked": true
}

启用写操作

为了启用写入操作，请更新您的 .env：

# Enable INSERT operations
ALLOW_INSERT_OPERATION=true

# Enable UPDATE operations
ALLOW_UPDATE_OPERATION=true

# Enable DELETE operations (use with caution!)
ALLOW_DELETE_OPERATION=true

更改权限后，重启MCP服务器。

安全最佳实践

  1. 默认为只读模式除非特别需要，否则保持写操作禁用状态
  2. 使用预编译语句总是使用 params 用于用户输入的数组
  3. 验证表名服务器在执行描述操作时验证表名
  4. 模式保护DROP/TRUNCATE/ALTER 操作已被永久阻止
  5. 连接池使用连接池以提高性能和资源管理效率

错误处理

服务器提供了详细的错误响应：

{
  "error": "Table 'db.nonexistent' doesn't exist",
  "code": "ER_NO_SUCH_TABLE",
  "sqlState": "42S02"
}

测试与验证

快速测试

一旦连接到您的MCP客户端，请尝试以下命令：

  1. 检查连接：

    Show me the MySQL database information

  2. 列出表格：

    What tables are in my database?

  3. 测试安全功能：

    Try to insert a test record into any table

    （应显示明确错误信息并阻止）

  4. 查询数据：

    Show me sample data from the users table

验证核对清单

  • [ ] 服务器在MCP客户端中显示为已连接
  • [ ] 数据库连接信息显示正确
  • [ ] 工作列表表
  • [ ] SELECT 查询执行成功
  • [ ] INSERT/UPDATE/DELETE 被阻止（默认）
  • [ ] 清除被阻止操作的错误信息

如需详细的测试示例，请参阅 示例/用法示例.md。

发展

# Build the project
npm run build

# Run the server directly (for testing)
npm start

# Build and run
npm run dev

# Watch mode (if needed)
npm run build -- --watch

项目结构

mcp-mysql-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── examples/             # Integration guides and examples
│   ├── claude-code-setup.md
│   ├── codex-cli-setup.md
│   └── usage-examples.md
├── .env.example          # Environment template
├── package.json
├── tsconfig.json
└── README.md

做出贡献

见 `CONTRIBUTING.md` 翻译为中文是：“贡献指南/贡献说明文件”。这个文件通常用于说明如何向项目贡献代码或内容，包括贡献的流程、规范、要求等 作为开发指南。

故障排除

连接问题

  • 验证 MySQL 是否正在运行： mysql -u username -p
  • 检查主机/端口配置
  • 验证用户凭据
  • 确保数据库存在

权限错误

  • 检查MySQL用户是否具有所需的权限
  • 验证 ALLOW_*_OPERATION 设置符合您的需求

未找到工具

  • 确保服务器已正确配置 .mcp.json
  • 验证构建是否成功： ls -la dist/index.js
  • 检查MCP客户端是否能找到服务器

资源

支持

  • 问题：通过 GitHub 问题页面报告错误或请求功能
  • 问题：检查一下 例子 常见用例目录
  • 安全性：如有关于安全性的担忧，请通过电子邮件联系维护人员

更新日志

版本 1.0.0

  • 首次发布
  • 基本的MySQL操作（SELECT，INSERT，UPDATE，DELETE）
  • 安全特性与操作阻力
  • 为防止SQL注入而准备的预编译语句
  • 连接池
  • 全面的文件记录

许可证

MIT - 查看 许可证 文件详情见附件

相关 MCP