mysql-mcp-pro

mysql-mcp-pro

🇺🇸 英語版はこちら

AI アシスタント（Claude Desktop / WorkBuddy / Cursor / Cline など）が標準化されたプロトコルを通じて MySQL データベースを安全かつ効率的に操作できる、本番環境対応の MySQL MCP サーバーです。

✨ mysql-mcp-pro を選ぶ理由

コミュニティの他の MySQL MCP 実装と比べて、このプロジェクトではより包括的な機能を提供しています。

特性	mysql-mcp-pro	その他の MCP
コネクションプール（ハンドシェイクのオーバーヘッドを削減）	✅	❌
トランザクションのサポート（begin/commit/rollback）	✅	❌
EXPLAIN の自動解析	✅	❌
結果を CSV/JSON でエクスポート（Excel で扱いやすい BOM）	✅	❌
ER 関係図データ（nodes/edges）	✅	少数
ビュー / ストアドプロシージャ / 関数 / トリガーの一覧表示	✅	少数
クエリ履歴と監査ログ	✅	❌
MCP プロンプトテンプレート（生成/最適化/比較/概要）	✅	❌
安全性の段階設定（読み取り専用/DDL/危険な文/タイムアウト/行数制限/パラメーター化）	✅	基本
複数の転送モード（stdio / SSE / streamable-http）	✅	一部

🚀 クイックスタート

1. インストール

# 从源码（推荐先 clone 再使用）
git clone https://github.com/CCCT173/mysql-mcp-pro.git
cd mysql-mcp-pro
pip install -e .

# 或从 PyPI（待发布）
pip install mysql-mcp-pro

2. 環境変数を設定

.env.example を .env にコピーして編集します。

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

READ_ONLY=false         # 只读模式
ALLOW_DDL=false          # 是否允许 CREATE/ALTER/DROP
MAX_RESULT_ROWS=1000     # 单次查询最大返回行数
QUERY_TIMEOUT=30         # 查询超时(秒)

POOL_SIZE=5
AUDIT_LOG=true           # 审计日志
EXPORT_DIR=./exports     # 导出目录

3. MCP クライアントに登録

WorkBuddy

~/.workbuddy/mcp.json を編集します。

{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "D:/path/to/mysql-mcp-pro",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

または、すでに pip install -e . を実行している場合：

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-pro",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%/Claude/claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-pro",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "READ_ONLY": "true"
      }
    }
  }
}

Cursor / Cline

プロジェクトのルートディレクトリに .cursor/mcp.json（Cursor）を作成するか、Cline の設定に追加します。形式は上記と同じです。

ツール

ツールは MCP レジストリ（Smithery、mcp.so、glama など）によって自動的に抽出されます。

• ping — MySQL 接続をテストし、サーバーのバージョンとコネクションプールの統計情報を返します。
• get_server_status — MySQL の主要なステータス指標（接続数、QPS、スロークエリ、InnoDB の行数、トラフィック）。
• list_databases — すべてのデータベースを一覧表示します（システムとユーザー）。
• list_tables — エンジン、行数、サイズ、コメントとともにテーブルを一覧表示します。database 引数は省略可能です。
• describe_table — テーブルスキーマを表示します。内容はカラム、主キー、インデックス、外部キー、CREATE SQL です。引数：table（必須）、database（省略可能）。
• list_views — データベース内のビューを一覧表示します。
• list_routines — ストアドプロシージャまたは関数を一覧表示します。引数：routine_type（PROCEDURE/FUNCTION）、database。
• list_triggers — データベース内のトリガーを一覧表示します。
• er_graph — テーブル間の外部キー関係をノードとエッジで表したグラフを返します。ER 図にそのまま利用できます。
• execute_query — 任意の SQL を実行します（読み取り/書き込み/DDL、安全性チェック付き）。パラメーター化に対応します。引数：sql、database、params、session_id。
• execute_select — 追加の安全対策を備えた読み取り専用の SELECT/SHOW/DESCRIBE/EXPLAIN を実行します。引数：sql、database、params、limit。
• get_table_data — ページネーションを使用してテーブルをすばやく取得します。引数：table、columns、where、order_by、limit、offset。
• count_rows — テーブルの行数を数えます。WHERE 条件は省略可能です。引数：table、database、where。
• explain_query — クエリに対して EXPLAIN を実行し、平易な言葉でパフォーマンスに関する分析を返します。引数：sql、database、params、format。
• export_query — SELECT の結果を CSV（UTF-8 BOM、Excel 対応）または JSON ファイルにエクスポートします。引数：sql、filename、format（csv/json）、database、params。
• list_query_history — このセッションで実行した最近の SQL（実行時間、行数、エラー）を表示します。引数：limit。
• begin_transaction — 新しいトランザクションを開始し、後続の呼び出しに使用する session_id を返します。引数：database。
• commit_transaction — 開いているトランザクションをコミットします。引数：session_id。
• rollback_transaction — 開いているトランザクションをロールバックします。引数：session_id。
• show_processlist — 現在の MySQL プロセス一覧（SHOW FULL PROCESSLIST）を表示します。
• kill_query — MySQL プロセスを終了します（SUPER 権限が必要です）。引数：process_id。

🛠 ツール一覧（25 個）

接続とステータス

• ping — 接続をテストし、サーバーのバージョンとコネクションプールのステータスを返します。
• get_server_status — MySQL の主要な指標（接続数、QPS、スロークエリ、トラフィックなど）。

元数据浏览

• list_databases — 列出所有数据库（区分系统库 / 用户库）
• list_tables — 列出表，含引擎、行数、大小、注释
• describe_table — 表结构：字段、主键、索引、外键、建表 SQL
• list_views — 列出视图
• list_routines — 列出存储过程 / 函数
• list_triggers — 列出触发器
• er_graph — 跨表外键关系（nodes + edges），便于画 ER 图

查询执行

• execute_query — 执行任意 SQL（读/写/DDL，受安全策略约束），支持参数化
• execute_select — 只读 SELECT 专用（即使配置错误也只允许读）
• get_table_data — 快速取数：columns / where / order_by / limit / offset
• count_rows — 统计行数（支持可选 WHERE）

分析 & 导出

• explain_query — EXPLAIN 执行计划 + 中文性能洞察
• export_query — 结果导出 CSV（UTF-8 BOM，Excel 友好）或 JSON 文件
• list_query_history — 本会话 SQL 历史（耗时 / 行数 / 错误）

事务

• begin_transaction — 开启事务，返回 session_id
• commit_transaction — 提交事务
• rollback_transaction — 回滚事务

监控 & 管理

• show_processlist — 当前 MySQL 进程列表
• kill_query — Kill 指定进程（需要 SUPER 权限）

MCP Resources（4 个）

• mysql://databases — 数据库列表
• mysql://tables/{database} — 表列表
• mysql://schema/{database}/{table} — 表结构
• mysql://er/{database} — ER 关系图数据

MCP Prompts（4 个模板）

• generate_query — 根据自然语言和表信息生成 SQL
• optimize_sql — 分析并优化现有 SQL 性能
• compare_schema — 对比两张表的结构差异
• database_summary — 数据库整体概览报告

🔒 安全模型

危险语句（GRANT/REVOKE/SHUTDOWN/KILL/FLUSH/RESET）→ 永远禁止
DDL（CREATE/ALTER/DROP/RENAME/TRUNCATE）            → 由 ALLOW_DDL 控制
写操作（INSERT/UPDATE/DELETE）                       → 由 READ_ONLY 控制
读操作（SELECT/SHOW/DESCRIBE/EXPLAIN）               → 永远允许

• 参数化查询 %s 占位符，杜绝 SQL 注入
• 结果集默认 1000 行上限，防止意外返回海量数据
• 服务端 MAX_EXECUTION_TIME 强制查询超时
• 所有执行 SQL 落盘到 exports/audit.log

📁 项目结构

mysql-mcp-pro/
├── server.py              # MCP 服务器（连接池 / 事务 / 导出 / 审计）
├── pyproject.toml         # 包元数据，入口 mysql-mcp-pro
├── .env.example           # 环境变量模板
├── LICENSE                # MIT
├── README.md / README.en.md
└── scripts/
    ├── setup_test_db.py   # 创建 mcp_test 样例数据库
    ├── test_v2.py         # 53 项回归测试
    └── diag.py            # MySQL 握手包诊断工具

🧪 本地测试

# 1. 创建样例数据库（mcp_test，users + orders 表，带外键）
python scripts/setup_test_db.py

# 2. 跑全量回归测试
python scripts/test_v2.py
# → 53 passed, 0 failed

🤝 贡献

欢迎提 issue 和 PR！请确保：

1. 新功能带测试用例
2. 现有测试全部通过
3. 遵循现有代码风格

📄 License

MIT