MySQL查询服务器 / MySQL Query Server

MySQL クエリサーバー / MySQL クエリサーバー

---

1. プロジェクト概要 / プロジェクト概要

本プロジェクトは、MCP フレームワークを基盤とする MySQL クエリサーバーです。SSE プロトコルを介したリアルタイムのデータベース操作をサポートします。包括的なセキュリティ、ログ、設定、機密情報保護の仕組みを備えており、開発、テスト、本番環境での安全な MySQL データアクセスに適しています。

本プロジェクトは、MCP フレームワークを基盤とする MySQL クエリサーバーで、SSE プロトコルを介したリアルタイムのデータベース操作をサポートします。包括的なセキュリティ、ログ、設定、機密情報保護の仕組みを備えており、開発、テスト、本番環境での安全な MySQL データアクセスに適しています。

---

2. 主な特長 / 主な特長

• FastMCP フレームワークを基盤とし、非同期で高いパフォーマンスを実現

• 高い同時実行性に対応したデータベース接続プールを備え、パラメーターを柔軟に調整可能

• SSE によるリアルタイムプッシュをサポート

• MySQL のメタデータおよびスキーマを照会する豊富な API

• トランザクションの自動管理とロールバック

• 多段階の SQL リスク制御とインジェクション対策

• データベース分離セキュリティ：データベース間のアクセスを防ぎ、3 段階のアクセス制御をサポート

• 機密情報の自動マスキングとカスタマイズ

• 柔軟な環境変数設定

• 充実したログとエラー処理

• Docker に対応し、迅速にデプロイ可能

• FastMCP フレームワークを基盤とし、非同期で高いパフォーマンスを実現

• 高い同時実行性に対応した接続プールを備え、パラメーターを柔軟に調整可能

• SSE によるリアルタイムプッシュをサポート

• MySQL のメタデータおよびスキーマを照会する豊富な API

• トランザクションの自動管理とロールバック

• 多段階の SQL リスク制御とインジェクション対策

• データベース分離セキュリティ：データベース間のアクセスを防ぎ、3 段階のアクセス制御を実現

• 機密情報の自動マスキングとカスタマイズ

• 柔軟な環境変数設定

• 充実したログとエラー処理

• Docker に対応し、迅速なデプロイが可能

---

3. クイックスタート / クイックスタート

Docker 方式 / Docker 方式

# 拉取镜像
docker pull mangooer/mysql-mcp-server-sse:latest

# 运行容器
docker run -d \
  --name mysql-mcp-server-sse \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -e MYSQL_HOST=your_mysql_host \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=your_mysql_user \
  -e MYSQL_PASSWORD=your_mysql_password \
  -e MYSQL_DATABASE=your_database \
  -p 3000:3000 \
  mangooer/mysql-mcp-server-sse:latest

Windows PowerShell 形式：

docker run -d `
  --name mysql-mcp-server-sse `
  -e HOST=0.0.0.0 `
  -e PORT=3000 `
  -e MYSQL_HOST=your_mysql_host `
  -e MYSQL_PORT=3306 `
  -e MYSQL_USER=your_mysql_user `
  -e MYSQL_PASSWORD=your_mysql_password `
  -e MYSQL_DATABASE=your_database `
  -p 3000:3000 `
  mangooer/mysql-mcp-server-sse:latest

ソースコード方式 / ソースコード方式

依存関係のインストール / 依存関係のインストール

pip install -r requirements.txt

環境変数の設定 / 環境変数の設定

.env.exampleを.envにコピーし、必要に応じて変更します。 .env.exampleを.envにコピーし、必要に応じて変更します。

サーバーの起動 / サーバーの起動

python -m src.server

デフォルトのエンドポイント：http://127.0.0.1:3000/sse デフォルトのエンドポイント：http://127.0.0.1:3000/sse

---

4. ディレクトリ構成 / プロジェクト構成

.
├── src/
│   ├── server.py           # 主服务器入口 / Main server entry
│   ├── config.py           # 配置项定义 / Config definitions
│   ├── validators.py       # 参数校验 / Parameter validation
│   ├── db/
│   │   └── mysql_operations.py # 数据库操作 / DB operations
│   ├── security/
│   │   ├── interceptor.py      # SQL拦截 / SQL interception
│   │   ├── query_limiter.py    # 风险控制 / Risk control
│   │   └── sql_analyzer.py     # SQL分析 / SQL analysis
│   └── tools/
│       ├── mysql_tool.py           # 基础查询 / Basic query
│       ├── mysql_metadata_tool.py  # 元数据查询 / Metadata query
│       ├── mysql_info_tool.py      # 信息查询 / Info query
│       ├── mysql_schema_tool.py    # 结构查询 / Schema query
│       └── metadata_base_tool.py   # 工具基类 / Tool base class
├── tests/                  # 测试 / Tests
├── .env.example            # 环境变量示例 / Env example
└── requirements.txt        # 依赖 / Requirements

---

5. 環境変数と設定 / 環境変数と設定

変数名 / 変数名	説明 / 説明	デフォルト値 / デフォルト値
HOST	サーバーのリッスンアドレス / サーバーのリッスンアドレス	127.0.0.1
PORT	サーバーのリッスンポート / サーバーのリッスンポート	3000
MYSQL_HOST	MySQLサーバーのホスト / MySQLサーバーのホスト	localhost
MYSQL_PORT	MySQLサーバーのポート / MySQLサーバーのポート	3306
MYSQL_USER	MySQLのユーザー名 / MySQLのユーザー名	root
MYSQL_PASSWORD	MySQLのパスワード / MySQLのパスワード	(空/空)
MYSQL_DATABASE	接続するデータベース名 / データベース名	(空/空)
DB_CONNECTION_TIMEOUT	接続タイムアウト時間（秒） / 接続タイムアウト時間（秒）	5
DB_AUTH_PLUGIN	認証プラグインの種類 / 認証プラグインの種類	mysql_native_password
DB_POOL_ENABLED	接続プールを有効にするかどうか / 接続プールを有効にする（true/false）	true
DB_POOL_MIN_SIZE	接続プールの最小接続数 / 接続プールの最小サイズ	5
DB_POOL_MAX_SIZE	接続プールの最大接続数 / 接続プールの最大サイズ	20
DB_POOL_RECYCLE	接続の再利用時間（秒） / 接続プールの再利用時間（秒）	300
DB_POOL_MAX_LIFETIME	接続の最大存続時間（秒、0=無制限） / 最大存続時間（秒）	0
DB_POOL_ACQUIRE_TIMEOUT	接続取得のタイムアウト時間（秒） / 接続取得のタイムアウト時間（秒）	10.0
ENV_TYPE	環境の種類（development/production） / 環境の種類	development
ALLOWED_RISK_LEVELS	許可するリスクレベル（カンマ区切り） / 許可するリスクレベル	LOW,MEDIUM
ALLOW_SENSITIVE_INFO	機密フィールドのクエリを許可するかどうか / 機密情報を許可する（true/false）	false
SENSITIVE_INFO_FIELDS	カスタム機密フィールドのパターン（カンマ区切り） / カスタム機密フィールド	(空/空)
MAX_SQL_LENGTH	SQL文の最大長 / SQLの最大長	5000
BLOCKED_PATTERNS	ブロックするSQLパターン（カンマ区切り） / ブロックするSQLパターン	(空/空)
ENABLE_QUERY_CHECK	クエリのセキュリティチェックを有効にする / クエリチェックを有効にする（true/false）	true
ENABLE_DATABASE_ISOLATION	データベース分離を有効にする / データベース分離を有効にする（true/false）	false
DATABASE_ACCESS_LEVEL	データベースのアクセスレベル / データベースのアクセスレベル（strict/restricted/permissive）	permissive
LOG_LEVEL	ログレベル（DEBUG/INFO/...） / ログレベル	DEBUG

注：一部のクラウドMySQLでは、DB_AUTH_PLUGINにmysql_native_passwordを指定する必要があります。

MySQL 8.0の認証サポート / MySQL 8.0の認証サポート

本システムはMySQL 8.0の認証方式を完全にサポートしています。MySQL 8.0では、セキュリティを強化するため、デフォルトでcaching_sha2_password認証プラグインが使用されます。

本システムはMySQL 8.0の認証方式を完全にサポートしています。MySQL 8.0では、セキュリティを強化するために、デフォルトでcaching_sha2_passwordが使用されます。

認証プラグインの比較 / 認証プラグインの比較

認証プラグイン / プラグイン	セキュリティ / セキュリティ	互換性 / 互換性	依存関係 / 依存関係
mysql_native_password	中 / 中	高 / 高	なし / なし
caching_sha2_password	高 / 高	中 / 中	cryptography

設定の推奨事項 / 設定の推奨事項

本番環境 / 本番環境（推奨 / 推奨）：

DB_AUTH_PLUGIN=caching_sha2_password

開発環境 / 開発環境（簡易設定 / 簡易設定）：

DB_AUTH_PLUGIN=mysql_native_password

依存関係のインストール / 依存関係のインストール

caching_sha2_passwordを使用するには、cryptographyパッケージのインストールが必要です（requirements.txtに含まれています）。

caching_sha2_passwordを使用する場合は、cryptographyパッケージが必要です（requirements.txtにすでに含まれています）。

pip install cryptography

データベース分離のセキュリティ / データベース分離のセキュリティ

本システムは、データベース間のアクセスを防ぎ、データの安全性を確保する強力なデータベース分離機能を備えています。

本システムは、データベース間のアクセスを防ぎ、データの安全性を確保するための堅牢なデータベース分離機能を提供します。

アクセスレベル / アクセスレベル

レベル / レベル	許可されるアクセス / 許可されるアクセス	ユースケース / ユースケース
strict	指定されたデータベースのみ / 指定されたデータベースのみ	本番環境 / 本番環境
restricted	指定されたデータベース＋システムデータベース / 指定されたデータベース＋システムデータベース	開発環境 / 開発環境
permissive	すべてのデータベース / すべてのデータベース	テスト環境 / テスト環境

データベース分離の有効化 / データベース分離の有効化

# Docker 启用严格模式 / Docker with strict mode
docker run -d \
  -e MYSQL_DATABASE=your_database \
  -e ENABLE_DATABASE_ISOLATION=true \
  -e DATABASE_ACCESS_LEVEL=strict \
  mangooer/mysql-mcp-server-sse:latest

# 生产环境自动启用 / Auto-enable in production
docker run -d \
  -e ENV_TYPE=production \
  -e MYSQL_DATABASE=your_database \
  mangooer/mysql-mcp-server-sse:latest

セキュリティ効果 / セキュリティ効果：

• ✅ SHOW DATABASES をブロックします / SHOW DATABASES をブロックします
• ✅ SELECT * FROM mysql.user をブロックします / SELECT * FROM mysql.user をブロックします
• ✅ SHOW TABLES FROM other_db をブロックします / SHOW TABLES FROM other_db をブロックします
• ✅ 現在のデータベースでの操作を許可します / 現在のデータベースでの操作を許可します

🔒 重要：本番環境（ENV_TYPE=production）では、restricted モードでデータベース分離が自動的に有効になります。

🔒 重要：本番環境（ENV_TYPE=production）では、restricted モードでデータベース分離が自動的に有効になります。

---

6. 自動化とリソース管理の最適化 / 自動化とリソース管理の強化

ツールの自動登録 / ツールの自動登録

• MySQL 関連の API ツールはすべて、自動登録の仕組みを採用しています。
  • メインエントリで登録コードを手動で管理する必要はありません。ツールを追加・削除するには、src/tools/ ディレクトリに register_xxx_tool(s) 関数を実装するだけです。
  • システム起動時にツールを自動的にスキャンして登録するため、保守性と拡張性が大幅に向上します。
• MySQL 関連の API ツールはすべて、自動的に登録されます。
  • メインエントリで登録コードを手動で管理する必要はありません。ツールを追加・削除するには、src/tools/ ディレクトリに register_xxx_tool(s) 関数を実装するだけです。
  • システムは起動時にツールを自動的にスキャンして登録し、保守性と拡張性を大幅に向上させます。

接続プールの自動再利用とリソース管理 / 接続プールの自動再利用とリソース管理

• 接続プールは、イベントループごとの分離と自動再利用の仕組みを採用しています。
  • イベントループごとに独立したプールを持ち、高い並行性と複数環境での運用に対応します。
  • 無効または使用されていないプールを、デフォルトでは5分ごとに自動的に再利用し、リソースリークを防止します。
  • イベントループが終了すると、対応する接続プールを自動的に閉じ、リソースを確実に解放します。
  • 複数データベース／マルチテナントのシナリオに対応できます。
• すべてのリソース管理操作は詳細にログへ記録されるため、追跡やトラブルシューティングが容易です。
• 接続プールは、イベントループごとの分離と自動再利用を行います。
  • イベントループごとに独立したプールを持ち、高い並行性と複数環境での運用に対応します。
  • 使用されていない、または無効なプールをデフォルトでは5分ごとに自動的に再利用し、リソースリークを防止します。
  • イベントループが終了すると、そのプールを自動的に閉じてリソースを完全に解放します。
  • 複数データベース／マルチテナントのシナリオに対応できます。
• すべてのリソース管理操作は詳細にログへ記録されるため、追跡やトラブルシューティングが容易です。

---

7. セキュリティ対策 / セキュリティ対策

• SQL リスクレベルを複数段階で設定（LOW/MEDIUM/HIGH/CRITICAL）

• SQL インジェクションや危険な操作を遮断

• WHERE 句の必須チェック

• データベース分離のセキュリティ：3段階のアクセス制御（strict/restricted/permissive）

• データベース間アクセスの保護：未許可のデータベースアクセスをブロック

• 機密情報を自動的にマスキング（カスタムフィールドに対応）

• 本番環境ではデフォルトで低リスクの操作のみ許可

• 本番環境ではデータベース分離を自動的に有効化

• SQL リスクレベルを複数段階で設定（LOW/MEDIUM/HIGH/CRITICAL）

• SQL インジェクションや危険な操作を遮断

• WHERE 句の必須チェック

• データベース分離のセキュリティ：3段階のアクセス制御（strict/restricted/permissive）

• データベース間アクセスの保護：未許可のデータベースアクセスをブロック

• 機密情報を自動的にマスキング（カスタマイズ可能なフィールド）

• 本番環境ではデフォルトで低リスクの操作のみ許可

• 本番環境ではデータベース分離を自動的に有効化

---

8. ログとエラー処理 / ログとエラー処理

• ログレベルを設定可能（LOG_LEVEL）

• コンソールとファイルへのログ出力

• 実行状況とエラーを詳細に記録

• 例外処理とトランザクションのロールバックを適切に実施

• ログレベルを設定可能（LOG_LEVEL）

• コンソールとファイルへのログ出力

• 実行状況とエラーを詳細に記録

• 堅牢な例外処理とトランザクションのロールバック

---

9. よくある質問 / よくある質問

Q: DELETE 操作が正常に実行されない場合は？

A: WHERE 条件があるか確認してください。WHERE 句がない場合は高リスクとなるため、ALLOWED_RISK_LEVELS で CRITICAL を許可する必要があります。

Q: DELETE が機能しないのはなぜですか？ A: WHERE 句があるか確認してください。WHERE 句のない DELETE は高リスク（CRITICAL）であり、ALLOWED_RISK_LEVELS で許可する必要があります。

Q: 機密フィールドをカスタマイズするには？

A: SENSITIVE_INFO_FIELDS を設定します。例：SENSITIVE_INFO_FIELDS=password,token

Q: 機密フィールドをカスタマイズするには？ A: SENSITIVE_INFO_FIELDS を設定します。例：SENSITIVE_INFO_FIELDS=password,token

Q: データベース分離を有効にするには？

A: ENABLE_DATABASE_ISOLATION=true と DATABASE_ACCESS_LEVEL=strict を設定するか、ENV_TYPE=production を使用すると自動的に有効になります。

Q: データベース分離を有効にするには？ A: ENABLE_DATABASE_ISOLATION=true と DATABASE_ACCESS_LEVEL=strict を設定するか、ENV_TYPE=production を使用すると自動的に有効になります。

Q: データベースの分離後にシステムテーブルをクエリできませんか？

A: strict モードではシステムテーブルへのアクセスが禁止されます。restricted モードに変更するか、システムテーブルへのアクセス権限が本当に必要かどうかを確認してください。

Q: データベースの分離を有効にした後、システムテーブルをクエリできませんか？ A: strict モードではシステムテーブルへのアクセスが禁止されます。restricted モードを使用するか、システムテーブルへのアクセスが本当に必要かどうかを確認してください。

Q: limit パラメーターでエラーが発生しますか？

A: limit は非負の整数である必要があります。

Q: limit パラメーターのエラーですか？ A: limit は非負の整数である必要があります。

---

10. 貢献ガイド / 貢献ガイド

Issue や Pull Request を通じた改善への貢献を歓迎します。 Issue や Pull Request を通じた貢献を歓迎します。

---

11. ライセンス / ライセンス

MIT License

本ソフトウェアは「現状有姿」で提供され、明示または黙示を問わず、いかなる種類の保証もありません。これには、商品性、特定目的への適合性、および非侵害性に関する保証が含まれますが、これらに限定されません。いかなる場合も、作者または著作権者は、本ソフトウェア、その使用、またはその他の取引に起因または関連して生じる、契約、不法行為、その他の訴訟におけるいかなる請求、損害、その他の責任についても責任を負いません。
本ソフトウェアは「現状有姿」で提供され、明示または黙示を問わず、いかなる種類の保証もありません。これには、商品性、特定目的への適合性、および非侵害性に関する保証が含まれますが、これらに限定されません。いかなる場合も、作者または著作権者は、本ソフトウェア、その使用、またはその他の取引に起因または関連して生じる、契約、不法行為、その他の訴訟におけるいかなる請求、損害、その他の責任についても責任を負いません。