mysqlDbMcp

生产级 MySQL MCP 服务：多数据源 YAML 配置，同时支持 MCP CLI（stdio） 与 MCP HTTP（Streamable HTTP），默认全局只读，兼容 MySQL 5.7 / 8.0。

仓库：https://github.com/ErrSilent/mysqlDbMcp

能力一览

类别	内容
元数据	库 / 表 / 字段 / 索引 / 主键 / 外键
查询	只读 SQL、EXPLAIN（可选 JSON）
安全	默认只读、危险 SQL 拦截、行数与超时、库表白名单、审计日志、参数化查询；写入需显式开关
连接	每数据源独立连接池、请求会话隔离、运行时按 datasource 切换
协议	Tools + Resources + Prompts；stdio / HTTP
可选模块	慢 SQL、健康巡检、测试数据生成、向量检索（YAML 开关，默认关闭）

快速开始（Linux / macOS）

./scripts/install.sh
cp config/config.example.yaml config/config.yaml
# 编辑 config/config.yaml 中的 datasources / security
./scripts/start-stdio.sh          # MCP CLI
# 或
./scripts/start-http.sh           # MCP HTTP → http://127.0.0.1:3100/mcp

快速开始（Windows）

scripts\install.bat
copy config\config.example.yaml config\config.yaml
scripts\start-stdio.bat
scripts\start-http.bat

手动启动：

npm ci && npm run build
node dist/index.js --mode stdio --config ./config/config.yaml
node dist/index.js --mode http  --config ./config/config.yaml

配置说明

所有业务参数来自外部 YAML，禁止依赖代码内硬编码。模板见 config/config.example.yaml。

要点：

• datasources[]：多 MySQL 源；第一项为默认源。
• security.readonly: true（默认）+ allow_write: false：彻底关闭写能力；run_write 不会注册。
• 打开写入必须同时满足：readonly: false、allow_write: true、目标源 force_readonly: false。即使用写打开，DROP/ALTER/TRUNCATE/CREATE/... 仍被拦截。
• max_rows / query_timeout_ms：结果截断与超时（5.7 用应用层超时；8.0 额外尝试 max_execution_time）。
• whitelist.databases / tables：库表白名单（* 表示不限制名称，但仍受账号权限约束）。
• security.audit：JSONL 全量操作审计。
• modules.*.enabled：可选模块开关。

MCP Tools

Tool	说明
list_datasources	列出数据源
list_databases	库列表（白名单过滤）
list_tables	表列表
describe_table	字段
list_indexes	索引
list_primary_keys	主键
list_foreign_keys	外键
run_query	只读 SQL（支持 params）
explain_query	执行计划
run_write	仅当写入开关打开时注册

Resources：mysql://datasources、mysql://{ds}/databases、mysql://{ds}/{db}/tables、mysql://{ds}/{db}/{table}/schema

Prompts：analyze_schema、optimize_query、draft_readonly_sql

调用示例

• Stdio / 客户端配置：examples/mcp-cli-call.md
• HTTP / curl：examples/mcp-http-call.md

生产安全清单

1. 生产账号只授予 SELECT（及必要的 SHOW VIEW / PROCESS 等），不要用高权限账号。
2. 保持 readonly: true、allow_write: false、各源 force_readonly: true。
3. 收紧 whitelist，避免 *。
4. 设置合理的 max_rows 与 query_timeout_ms。
5. 开启审计并轮转 logs/audit.jsonl。
6. HTTP 模式务必配置 server.http.auth_token，并在反向代理终止 TLS。
7. 客户端优先使用 params 参数化，避免拼接 SQL。
8. 错误以结构化 JSON 返回：{ "code", "message", "details?" }。

开发与验证

npm run typecheck
npm run seed          # 需要本地 MySQL（默认 mcp/mcp @ mcp_demo）
npm run e2e           # stdio 端到端（含危险 SQL 拒绝）

Cursor Cloud Agent 环境见 .cursor/（MySQL 8 + Node 22，启动时初始化演示库）。

许可证

以仓库声明为准。