mysql-mcp

MySQL MCP サーバー（mysql-mcp）

📚 ドキュメント全文（Wiki） • 変更履歴 • セキュリティ • リリース記事

💎 提供価値

AI エージェントを本番環境対応の MySQL 環境に統合します。HTTP トランスポートを介して、ステートレスな MCP v2 アーキテクチャをデプロイできます。Code Mode によってトークン効率を最適化します。OAuth 2.1 でデータベースを保護します。

🎯 コアメリットを活用

機能	説明
特化型ツール	CRUD、JSON、空間データ、ドキュメントストア、クラスター向けの特化型ツールを利用できます。
リソース	スキーマ、パフォーマンス指標、プロセス一覧、レプリケーションの状態、InnoDB の診断情報をリアルタイムで監視できます。
AI 対応プロンプト	クエリの作成、スキーマ設計、パフォーマンス調整、インフラストラクチャのセットアップに関するガイド付きワークフローを実行できます。
コードモード	セキュアなサンドボックス化された V8 アイソレート内に操作を集約して、LLM のトークン消費量を削減します。
トークン最適化ペイロード	トークン効率を最大化します。オプションのフラグを使用すると、大きなペイロードの応答サイズを削減できます。
OAuth 2.1 セキュリティ	RFC 準拠、厳格なスコープ、Keycloak との統合により、きめ細かなアクセス制御を適用します。
スマートなツールのフィルタリング	ツールグループとショートカットを使用して、IDE のツール制限内に収められます。
ストリーミング可能なステートレス HTTP	MCP v2 のストリーミング可能な HTTP とステートレス HTTP のデプロイメントをサポートします。
コネクションプーリング	組み込みのコネクションプーリングを活用して、効率的で高度に並行したデータベースアクセスを実現します。
エコシステムとの統合	エージェントから MySQL Router、ProxySQL、MySQL Shell のユーティリティを直接管理できます。
高度な暗号化	TLS/SSL 接続を適用します。データマスキング、暗号化の監視、コンプライアンスを簡単に管理できます。
本番環境に対応したセキュリティ	パラメーター化クエリによって SQL インジェクションを防止します。厳格な入力検証と監査ログを活用できます。
予測可能なエラー	実行可能な提案を含む構造化された応答を受け取れます。サイレント失敗や未加工の例外を排除します。
オブザーバビリティ	Prometheus 指標をエクスポートします。Dozzle でコンテナログを、Grafana Alloy/Loki で監査証跡を追跡できます。
厳格な TypeScript	堅牢なテストスイートに裏付けられた厳格な TypeScript を利用できます。
MCP v2 準拠	MCP v2 仕様を完全にサポートします。ステートレスルーティング、キャッシュ、安全性に関するヒント、通知が含まれます。

---

🤖 ガイド付きワークフローでタスクを自動化

このサーバーには、ガイド付きワークフロー用のインテリジェントなプロンプトが含まれています。

プロンプト	説明
mysql_tool_index	カテゴリ別の完全なツール一覧
mysql_quick_query	クエリをすばやく実行するショートカット
mysql_quick_schema	スキーマをすばやく調査
mysql_setup_observability	オブザーバビリティスタックの完全なセットアップガイド（Datadog など）

注：これは利用可能なプロンプトの一部です。mysql_tool_index を使用して、ガイド付きワークフローの全リストを確認してください。

---

📊 リソースで可観測性を向上

このサーバーは、データベースの可観測性とテレメトリーのための包括的なリソース一式を公開します。

リソース	カテゴリ	説明
mysql://schema	コア	データベーススキーマ全体
mysql://tables	コア	メタデータ付きのテーブル一覧
mysql://variables	コア	サーバー構成変数
mysql://status	コア	サーバーステータスのメトリクス
mysql://processlist	コア	アクティブな接続とクエリ
mysql://pool	コア	接続プールの統計情報
mysql://capabilities	拡張	サーバーのバージョン、機能、ツールのカテゴリ
mysql://health	拡張	データベースの包括的な健全性ステータス
mysql://performance	拡張	クエリパフォーマンスのメトリクス
mysql://indexes	拡張	インデックスの使用状況と統計情報
mysql://replication	拡張	レプリケーションのステータスと遅延
mysql://innodb	拡張	InnoDB バッファプールとエンジンのメトリクス
mysql://events	ドメイン	Event Scheduler のステータスとスケジュール済みイベント
mysql://sysschema	ドメイン	sys スキーマの診断概要
mysql://locks	ドメイン	InnoDB のロック競合の検出
mysql://cluster	ドメイン	Group Replication / InnoDB Cluster のステータス
mysql://spatial	ドメイン	空間カラムとインデックス
mysql://docstore	ドメイン	Document Store のコレクション
mysql://insights	分析	mysql_append_insight によるビジネスインサイトのメモ
mysql://metrics	可観測性	メモリ内のトークン使用量、レイテンシ、リクエストのメトリクス
mysql://audit	可観測性	システムエラーのフォレンジック記録とスナップショット
mysql://help	ドキュメント	重要な注意点と API の概要リファレンス
mysql://help/{group}	ドキュメント	グループごとに動的に表示されるツールリファレンス（例：core、codemode）

---

🚀 AI データベースをデプロイ

前提条件を確認

• Node.js >= 24.0.0（固定されたローカル開発バージョンについては .node-version を参照してください）
• Bun（リポジトリの自動化スクリプトの実行に使用）
• MySQL サーバー
• pnpm

サーバーをインストール

NPM / PNPM でインストール

pnpm add -g @neverinfamous/mysql-mcp

サーバーを実行します。

mysql-mcp --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

または、インストールせずに npx を使用します。

npx @neverinfamous/mysql-mcp --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

Docker で実行

名前空間に関する注意： Docker イメージでは writenotenow 名前空間を使用します。GitHub リポジトリでは neverinfamous を使用します。

Linux ユーザー向け： Linux で host.docker.internal を使用するには、--add-host host.docker.internal:host-gateway を指定してコンテナを実行してください。

docker run -i --rm -v ./data:/app/data -v ./logs:/var/log/mysql-mcp writenotenow/mysql-mcp:latest \
  --transport stdio \
  --allowed-io-roots /app/data \
  --mysql "mysql://mcp_user:[email protected]:3306/testdb"

Docker Compose で可観測性を有効化

同梱のテンプレートを使用して、可観測性スタック全体を起動します。Datadog、OpenTelemetry、Prometheus、Grafana が含まれています。これにより、MCP サーバー、MySQL データベース、Redis、可観測性サイドカーが起動します。

cd examples/basic-mysql-datadog
cp .env.example .env
docker compose up -d

• Grafana： http://localhost:3001 で利用できます（ダッシュボードは読み込み済みです）。
• Prometheus： http://localhost:9090 で利用できます。
• MCP サーバー： http://localhost:3000 で利用できます。

Datadog と OpenTelemetry の可観測性ルールに従う

Datadog の制約：

• 認証：認証には pup CLI を使用します。
• 自動検出：自動検出の設定が重複しないようにしてください。コンテナに標準の追跡ラベル（tags.datadoghq.com/env、tags.datadoghq.com/service、tags.datadoghq.com/version）を追加してください。
• WSL2 の強化制限：stop_grace_period: 30s、mem_limit: 1536m、OpenMetrics のタイムアウト 10s を適用してください。
• ホスト設定：DD_HOSTNAME と、ネイティブの /etc/docker/daemon.json cgroup 設定（"default-cgroupns-mode": "host"）を使用してください。DD_EXTRA_PERFORMANCE_METRICS は無効にしてください。
• Windows のファイルテーリング：Docker／WSL2 のログマッピングでは、Windows の inotify テーリングに問題が発生する場合があることに注意してください。

OpenTelemetry のルール：

• セマンティック規約：gen_ai.* のセマンティクスを適用してください。
• 計装：可能な場合は自動計装を使用してください。
• コンテキスト伝搬：traceparent と tracestate が伝搬されるようにしてください。
• 処理とロギング：バッチプロセッサを使用し、ログが JSON ログとしてフォーマットされるようにしてください。

監査アーキテクチャとエクスポーターのヘルスチェック：

• プライマリ MCP サーバーは、--audit-log フラグを介して実行トレースを mcp-audit.jsonl に書き込みます。
• メトリクスエクスポーターは、独立したサイドカープロセスとして実行されます。AUDIT_LOG_PATH 環境変数を使って mcp-audit.jsonl を読み込み、メトリクスを計算します。
• エクスポーターは、--audit-log フラグを exporter-audit.jsonl に設定することで、内部ログを分離します。
• メトリクスサーバーとエクスポーターは単一のプロセスを共有します。どちらもポート 3000 で動作します。これにより、ポートの競合を防ぎます。
• エクスポーターのヘルスチェック：wget --spider -q http://127.0.0.1:3000/metrics

ソースからビルドする

git clone https://github.com/neverinfamous/mysql-mcp.git
cd mysql-mcp
pnpm install
pnpm run build
node dist/cli.js --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

---

🏗️ インフラストラクチャテンプレートを使用する

examples/ ディレクトリに、本番環境ですぐに使える Docker Compose テンプレートを用意しています。これらを使うと、テスト環境をすばやく起動できます。テンプレートには、Datadog の可観測性機能（メトリクス、APM、ログ）がすぐに使える状態で含まれています。

• 基本テンプレート： 軽量なシングルノードの MySQL セットアップです。手早く始めるのに最適です。
• エンタープライズ HA テンプレート： MySQL Router と ProxySQL を備えた、高可用性の InnoDB Cluster です。ステージング環境や本番環境のレプリカに最適です。
• 完全な可観測性エコシステム： Datadog、Prometheus、Grafana、Loki、Alloy を備えた、エンタープライズ向けの完全な監視スタックです。メトリクス設定の詳細については、可観測性 Wiki をご覧ください。

クイックスタート手順については、各ディレクトリの README をご覧ください。

---

⚡ コードモードでトークン使用量を最適化する

コードモード（mysql_execute_code）は、安全なサンドボックス内で複数の操作をまとめることで、トークン使用量を削減します。

コードは C++ V8 アイソレートサンドボックス内で安全に実行されます。厳格なヒープ制限を適用し、同期的に実行を終了します。ネイティブラッパーが、境界を越えるすべての API 呼び出しをマッピングします。これにより、多層防御とフリート標準の制限が確実に適用されます。

エンジンレベルの制限を適用する

• ✅ 厳格な V8 アイソレート境界 — コードは物理的に分離された V8 アイソレート内で実行されます。ネイティブオブジェクトやプロトタイプが境界を越えられないようにします。
• ✅ メモリと CPU の制約 — C++ レベルで適用されます。同期タイムアウトと厳格なヒープ制限が含まれます。
• ✅ 参照による API バインディング — ivm.Reference ラッパーを使って MySQL メソッドを安全に注入します。

コードを静的に検証する

• ✅ 包括的なブロックパターン — 正規表現ルールにより、require()、import()、eval()、Function、process、__proto__ をブロックします。また、ファイルシステム／ネットワークへのアクセスとシステムコマンドもブロックします。
• ✅ Unicode とコメントのサニタイズ — コメントを除去し、正規表現による回避を防ぐために NFKC 正規化を実行します。
• ✅ 設定可能なコード入力制限 — ペイロードによるリソース枯渇を防ぎます。

ランタイムを保護する

• ✅ RPC クォータ — 実行ごとの RPC API 呼び出し数に上限を設けます。これにより、無限ループを防ぎます。
• ✅ 実行タイムアウト — リソースの枯渇を防ぐため、タイムアウトを強制します。スキーマの timeout で設定できます。
• ✅ 送信境界の適用 — ストリーミングによる JSON.stringify のシリアライズは、サイズ上限を超えると処理の途中で中止されます。
• ✅ レート制限 — クライアントごとの上限（CODEMODE_RATE_LIMIT_MAX）を適用します。Redis を使用し、メモリ内のフォールバックにも対応します。
• ✅ 読み取り専用の適用 — readonly: true の場合、書き込みメソッドを実行せず、構造化エラーを返します。
• ✅ 監査ログ — UUID、クライアント ID、メトリクス、コードのプレビュー（機密情報をマスキング済み）を含む各実行のログを記録します。
• ✅ 管理者スコープ — OAuth が有効な場合、Code Mode には admin スコープが必要です。
• ✅ API へのフルアクセス — mysql.* 名前空間を通じて、すべてのツールグループを公開します。

⚡ Code Mode のみを実行する

Code Mode のみを有効にして実行します。単一のツールで、すべての機能にアクセスできます。推奨される IDE の設定については、以下の**オプション 1：Code Mode**をご覧ください。

公開されるのは mysql_execute_code のみです。エージェントは型付けされた SDK を使って JavaScript を記述します。クエリを組み合わせ、ツールグループをまたいで操作を連鎖させ、1 回の実行で必要なデータだけを返します。これは標準的なサーバーレスエッジ実行パターンに倣ったもので、トークンコストを一定に保ちます。

ヒント

トークンを最大限節約： AI エージェントには Code Mode を優先するよう指示してください。

「mysql-mcp の使用時は、複数ステップの操作には mysql_execute_code（Code Mode）を優先してください。これにより、トークンの使用量を最小限に抑えられます。」

最大限に節約するには、--tool-filter codemode を使い、Code Mode のみをツールとして実行してください。API の詳細については、Code Mode wikiをご覧ください。

---

🌐 Streamable HTTP と Stateless HTTP によるリモートアクセスを有効にする

HTTP モードを使用する場面： mysql-mcp をスタンドアロンサーバーとしてデプロイします。複数のクライアントがリモートから接続できます。ローカル開発には stdio モードを使用してください。

HTTP モードのユースケース：

• ネットワークからアクセス可能な Docker コンテナでサーバーを実行する
• クラウドプラットフォーム（AWS、GCP、Azure）にデプロイする
• エンタープライズセキュリティ向けに OAuth 2.1 認証を有効にする
• 複数の AI クライアントで 1 つのデータベース接続を共有する

リモートアクセスには HTTP トランスポートを使用してください：

npx -y @neverinfamous/mysql-mcp \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --allowed-io-roots /path/to/data \
  --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

Docker：

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  -v ./logs:/var/log/mysql-mcp \
  -e MCP_AUTH_TOKEN=my-secret-token \
  writenotenow/mysql-mcp:latest \
  --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /app/data --mysql "mysql://mcp_user:[email protected]:3306/testdb"

サーバーはStreamable HTTP と Stateless HTTP のデプロイに対応しています。ステートフルクライアントとステートレスクライアントのどちらも接続できます：

Streamable HTTP を使用する（推奨）

最新の MCP プロトコルです。単一エンドポイントでセッションを管理します：

メソッド	エンドポイント	用途
POST	/mcp	JSON-RPC リクエスト（initialize、tools/list など）
GET	/mcp	サーバー通知用の SSE ストリーム
DELETE	/mcp	セッションの終了

レート制限： HTTP トランスポートには IP ごとのレート制限があります（デフォルトは 100 回／分、MCP_RATE_LIMIT_MAX で設定可能）。Redis を使い、メモリ内のフォールバックを適切に利用することで、デプロイ間で制限を分散できます。

サーバーは Mcp-Session-Id ヘッダーを使用してセッションを管理します。

ステートレスで実行する

セッションが不要な場合は、ステートレスなデプロイを使用します：

node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --stateless --mysql "mysql://mcp_user:secure_password@..."

ステートレスモードでは、GET /mcp は 405 を返し、DELETE /mcp は 204 を返します。POST /mcp のたびに、ステートレス HTTP トランスポートがインスタンス化されます。

ユーティリティエンドポイントにアクセスする

メソッド	エンドポイント	用途
GET	/health	ヘルスチェック（レート制限を回避し、監視用として常に利用可能）
GET	/metrics	Prometheus メトリクスを出力（--metrics-export が有効な場合に利用可能）

🔐 認証でデータを保護する

mysql-mcp は HTTP トランスポート向けに、2 つの認証方式をサポートしています：

Bearer トークンで認証する（--auth-token）

開発には軽量な認証を使用します。

node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --auth-token my-secret --mysql "mysql://mcp_user:secure_password@..."

# Or via environment variable
export MCP_AUTH_TOKEN=my-secret
node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --mysql "mysql://mcp_user:secure_password@..."

クライアントはすべてのリクエストに Authorization: Bearer my-secret を含める必要があります。/health と / は対象外です。認証されていないリクエストには 401 が返されます。レスポンスには RFC 6750 に準拠した WWW-Authenticate: Bearer ヘッダーが含まれます。

OAuth 2.1 で認証する

本番環境へのデプロイには、完全な OAuth 2.1 を使用します。

node dist/cli.js \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --allowed-io-roots /path/to/data \
  --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb" \
  --oauth-enabled \
  --oauth-issuer https://localhost:8080/realms/mysql-mcp \
  --oauth-audience mysql-mcp-client

追加フラグ： --oauth-jwks-uri <url>（省略時は自動検出）、--oauth-clock-tolerance <seconds>（デフォルト：60）。

OAuth スコープを適用する

OAuth スコープを使用してアクセス制御を適用します。

スコープ	アクセスレベル
read	読み取り専用クエリ（SELECT、EXPLAIN）
write	読み取り＋書き込み操作
admin	完全な管理者アクセス
full	すべてのアクセス権を付与
db:{name}	特定のデータベースへのアクセス
table:{db}:{table}	特定のテーブルへのアクセス

RFC 準拠を確保する

この実装は、本番環境のマルチテナントデプロイ向けに完全な OAuth 2.1 に準拠しています。

• ✅ RFC 9728 保護対象リソースメタデータ（/.well-known/oauth-protected-resource）
• ✅ RFC 8414 キャッシュ対応の認可サーバー検出
• ✅ RFC 7591 OAuth 2.1 動的クライアント登録
• ✅ JWT 検証 JWKS 対応（TTL：1 時間）
• ✅ MySQL 固有のスコープ：read、write、admin、full、db:{name}、table:{db}:{table}
• ✅ AsyncLocalStorage コンテキストのスレッド化によるツールごとのスコープ適用

Keycloak ユーザーへの注意： クライアントに Audience mapper を追加してください。これにより、正しい aud クレームが含まれます。（Client → Client scopes → dedicated scope → Add mapper → Audience）

メモ

ツールごとのスコープ適用： サーバーはツールレベルでスコープを適用します。各ツールグループには特定のスコープが必要です。OAuth が有効な場合、各ツールの呼び出しでは、実行前に呼び出し元のトークンのスコープが確認されます。OAuth が設定されていない場合、サーバーはスコープチェックを一切行いません。

警告

認証なしの HTTP： 認証なしで --transport http を公開すると、制限のないアクセスが許可されます。本番環境の HTTP デプロイでは、必ず認証を有効にしてください。詳細は SECURITY.md を参照してください。

⚡ クライアント設定で AI 統合を簡素化

エージェントスキルをインストールする

AI のパフォーマンスを最適化するため、mysql-mcp には skills/ ディレクトリに専用のエージェント指示が含まれています。これらのスキルは、Cline、Antigravity、Copilot などの AI コーディングアシスタントに、サーバーの機能、ツールフィルター、Code Mode を効果的に使用する方法を教えます。

インストールするには、skills/ ディレクトリの .md ファイルを、AI アシスタント用の指定されたスキルフォルダーまたはカスタム指示フォルダー（例：.cursor/rules/、.agents/skills/ など）にコピーします。これにより、エージェントは使用方法を誤って作り出すことなく、mysql-mcp エコシステムを自律的に操作できるようになります。

IDE 設定を構成する

IDE の MCP 設定ファイルに設定を追加します。

オプション 1：Code Mode（トークンを最大限節約、🌟 推奨）

最適な用途： 一般的な MySQL AI エージェントのタスク。mysql_execute_code を公開し、サンドボックス化されたツールセット全体へのアクセスを提供します。

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "codemode"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "secure_password",
        "MYSQL_DATABASE": "testdb"
      },
      "timeout": 600
    }
  }
}

オプション 2：クラスター（InnoDB Cluster モニタリング用のツール）

最適な用途： InnoDB Cluster、Group Replication のステータス、クラスターのトポロジーのモニタリング。

⚠️ 前提条件：

• InnoDB Cluster が構成済みで稼働しており、Group Replication が有効になっていること
• クラスターのノードに直接接続すること（例：localhost:3307）。スタンドアロンの MySQL インスタンスには接続しないでください
• 適切な権限を持つ cluster_admin または root ユーザーを使用すること
• クラスターのセットアップ手順については、MySQL Ecosystem Setup Guide を参照してください

{
  "mcpServers": {
    "mysql-mcp-cluster": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "cluster"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3307",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "mysql"
      },
      "timeout": 600
    }
  }
}

オプション 3：エコシステム（InnoDB Cluster のデプロイ向けツール）

最適な用途： MySQL Router、ProxySQL、MySQL Shell、および InnoDB Cluster のデプロイ。

⚠️ 前提条件：

• InnoDB Cluster を利用するには、クラスターが稼働している必要があります。これにより、Router REST API の認証が有効になります。
• Router REST API は自己署名 HTTPS 証明書を使用します。検証を回避するには、MYSQL_ROUTER_INSECURE=true を設定してください。
• X Protocol： InnoDB Cluster には、デフォルトで MySQL X Plugin が含まれています。MYSQL_XPORT に Router の X Protocol ポート（例：6448）を設定してください。これにより、mysqlsh_import_json ツールと docstore ツールが有効になります
• 詳しい手順については、MySQL Ecosystem Setup Guide をご覧ください

{
  "mcpServers": {
    "mysql-mcp-ecosystem": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "ecosystem"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3307",
        "MYSQL_XPORT": "6448",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "testdb",
        "MYSQL_ROUTER_URL": "https://localhost:8443",
        "MYSQL_ROUTER_USER": "rest_api",
        "MYSQL_ROUTER_PASSWORD": "router_password",
        "MYSQL_ROUTER_INSECURE": "true",
        "PROXYSQL_HOST": "localhost",
        "PROXYSQL_PORT": "6032",
        "PROXYSQL_USER": "radmin",
        "PROXYSQL_PASSWORD": "radmin",
        "MYSQLSH_PATH": "mysqlsh"
      },
      "timeout": 600
    }
  }
}

注： ポート 6448 は、MySQL Router の標準 X Protocol ポートです。

カスタマイズに関する注意事項：

• /path/to/mysql-mcp/ を実際のインストールパスに置き換えてください。これはソースからビルドする場合にのみ必要です。ローカルファイルを直接実行する場合にも必要です。
• 認証情報を実際の値に更新してください
• Windows の場合：スラッシュ（例：C:/mysql-mcp/dist/cli.js）を使用するか、バックスラッシュをエスケープしてください
• Windows 版 MySQL Shell の場合："MYSQLSH_PATH": "C:\\Program Files\\MySQL\\MySQL Shell\\bin\\mysqlsh.exe"
• Router の認証： Router REST API は InnoDB Cluster のメタデータを使って認証します。認証を機能させるには、クラスターが稼働している必要があります。
• クラスターリソース： InnoDB Cluster のノードに接続します。これにより、mysql://cluster リソースが利用可能になります

📖 設定オプションの詳細については、Configuration Wiki をご覧ください。

---

🔗 あらゆる MySQL 環境と連携

シナリオ	使用するホスト	接続文字列の例
ホストマシン上の MySQL	localhost / host.docker.internal	mysql://mcp_user:secure_password@localhost:3306/testdb
Docker 内の MySQL	コンテナー名またはネットワーク	mysql://mcp_user:secure_password@mysql-container:3306/testdb
リモート／クラウド MySQL	ホスト名または IP	mysql://mcp_user:[email protected]:3306/testdb

ホストマシン上の MySQL に接続する

ネイティブのローカルインストールでは、localhost を使用してください。サーバーを Docker で実行している場合は、host.docker.internal を使用してください。

[
  "--mysql",
  "mysql://mcp_user:[email protected]:3306/testdb"
]

別の Docker コンテナー内の MySQL に接続する

Docker の設定では、host.docker.internal を使用してください。Docker Compose の場合は、mysql サービス名を使用してください。

ネットワークを作成し、MySQL を実行します。

docker network create mynet
docker run -d --name mysql-db --network mynet -e MYSQL_ROOT_PASSWORD=pass mysql:latest

同じネットワーク上で MCP サーバーを実行します。

docker run -i --rm --network mynet writenotenow/mysql-mcp:latest \
  --transport stdio --mysql "mysql://mcp_user:secure_password@mysql-db:3306/testdb"

リモート／クラウド MySQL に接続する（RDS、Cloud SQL など）

リモートのホスト名を直接使用してください。

[
  "--mysql",
  "mysql://mcp_user:[email protected]:3306/testdb"
]

プロバイダー	ホスト名の例
AWS RDS	your-instance.xxxx.us-east-1.rds.amazonaws.com
Google Cloud SQL	project:region:instance（Cloud SQL Proxy 経由）
Azure MySQL	your-server.mysql.database.azure.com
PlanetScale	aws.connect.psdb.cloud（SSL が必要）
DigitalOcean	your-cluster-do-user-xxx.db.ondigitalocean.com

ヒント： リモート MySQL サーバーが Docker の IP 範囲からの接続を許可していることを確認してください。ファイアウォール／セキュリティグループでポート 3306 が許可されていることを確認してください。

---

🛠️ ツールのフィルタリングで制限を最適化する

重要

Cursor などの AI IDE にはツール数の上限があります。IDE の上限に対応できるよう、ツールをフィルタリングしてください。専用ツールを多数提供しています。 すべてのショートカットとツールグループには、デフォルトで Code Mode が含まれています。これを除外するには、フィルターに -codemode を追加してください：--tool-filter core,json,-codemode

フィルタリングオプションを確認する

--tool-filter 引数は、ショートカット、グループ、またはツール名を受け付けます。自由に組み合わせて指定できます。

フィルターパターン	例	説明
ショートカットのみ	starter	事前定義されたバンドルを使用します
グループのみ	core,json,transactions	個別のグループを組み合わせます
ショートカット + グループ	starter,spatial	ショートカットを拡張します
ショートカット - ツール	starter,-mysql_drop_table	特定のツールを除外します

事前定義されたショートカットを使用する

ショートカット	用途	含まれるもの
starter	標準パッケージ	core, json, transactions, text, codemode
essential	最小構成	core, transactions, codemode
dev-power	パワーユーザー向け開発	core, schema, performance, fulltext, transactions, codemode
dev-analytics	開発者向け分析	core, stats, performance, codemode
ai-data-nosql	AI データ NoSQL	core, json, docstore, codemode
ai-search	AI 検索	core, text, fulltext, vector, codemode
ai-spatial	AI 空間分析	core, spatial, transactions, codemode
ai-vector	AI ベクトル分析	core, vector, fulltext, codemode
dba-monitor	DBA 監視	core, monitoring, performance, sysschema, optimization, codemode
dba-manage	DBA 管理	core, admin, backup, replication, partitioning, events, codemode
dba-secure	DBA セキュリティ	core, security, roles, transactions, codemode
dba-schema	DBA スキーマ	core, schema, introspection, migration, codemode
base-relational	基本的なリレーショナル機能	core, transactions, text, schema, codemode
base-analytics	基本的な分析機能	stats, events, codemode
base-nosql	基本的な NoSQL 機能	docstore, spatial, vector, codemode
ecosystem	外部ツール	cluster, proxysql, router, shell, codemode

ツールグループでフィルタリングする

注：Code Mode（mysql_execute_code）は、すべてのグループに自動的に追加されます。

グループ	説明
codemode	Code Mode（サンドボックス化されたコード実行）🌟 推奨
core	読み書きクエリ、テーブル、インデックス
transactions	BEGIN、COMMIT、ROLLBACK、セーブポイント
json	JSON 関数、マージ、差分、統計
text	REGEXP、LIKE、SOUNDEX
fulltext	自然言語検索とブール検索
performance	EXPLAIN、クエリ分析、異常検出
optimization	インデックスヒント、データベース全体の監査、EXPLAIN による推奨事項
admin	OPTIMIZE、ANALYZE、CHECK、分析情報
monitoring	PROCESSLIST、ステータス変数
backup	エクスポート、インポート、mysqldump、バックアップ監査
replication	マスター／スレーブ、binlog
partitioning	パーティション管理
schema	ビュー、プロシージャ、トリガー、制約
introspection	依存関係グラフ、カスケードのシミュレーション、スナップショット
migration	スキーマのバージョン管理、適用、ロールバック、履歴
shell	MySQL Shell ユーティリティ
events	Event Scheduler の管理
sysschema	sys スキーマの診断
stats	統計分析、ウィンドウ関数、サンプリング
spatial	空間／GIS 操作
security	監査、SSL、暗号化、マスキング
roles	MySQL ロールの管理
docstore	Document Store のコレクション
cluster	Group Replication、InnoDB Cluster
proxysql	ProxySQL の管理
router	MySQL Router REST API
vector	ベクトル埋め込み、KNN 検索、ハイブリッド検索

---

レビュー構文リファレンス

レガシー構文（引き続きサポートされています）： 負のフィルター（例：-ecosystem）から始めると、まずすべてのツールが有効になります。その後、指定したツールが差し引かれます。

プレフィックス	対象	例	効果
(none)	ショートカット	starter	ホワイトリストモード： このショートカットのみを有効にします
(none)	グループ	core	ホワイトリストモード： このグループのみを有効にします
(none)	ツール	mysql_read_query	ホワイトリストモード： このツールのみを有効にします
+	グループ	+spatial	このグループのツールを現在のセットに追加します
-	グループ	-admin	このグループのツールを現在のセットから削除します
+	ツール	+mysql_explain	特定のツールを1つ追加します
-	ツール	-mysql_drop_table	特定のツールを1つ削除します

ツール選択をカスタマイズする

カスタムのホワイトリストを作成するには、ツール名を + プレフィックスなしで列挙します。

フィルターを適用する最も簡単な方法は、ホワイトリストモードを使用することです。有効にしたいショートカットを指定するだけです。それ以外はすべて自動的に無効になります。

# Enable specific tools (whitelist mode)
--tool-filter "mysql_read_query,mysql_write_query,mysql_list_tables"

# Mix tools from different groups
--tool-filter "mysql_read_query,mysql_explain,mysql_json_extract"

# Combine with a shortcut or group
--tool-filter "starter,+mysql_spatial_distance,+mysql_json_diff"

最小限の機能セットを必要とする自動化クライアントには、この方法を使用してください。

📖 詳しい例については、ツールフィルタリング Wikiをご覧ください。

---

🔧 高度な設定でカスタマイズする

セットアップの詳細については、プロジェクトのルートにある設定テンプレートをご覧ください。

用途に応じたセットアップについては、次の Wiki ページをご覧ください。

トピック	説明
MySQL Router	InnoDB Cluster 用の Router REST API アクセスを設定します
ProxySQL	ProxySQL 管理インターフェースへのアクセスを設定します
MySQL Shell	ダンプ／ロード操作用に MySQL Shell を設定します

---

⚡ サーバーのパフォーマンスを最大化する

サーバーはスキーマメタデータをキャッシュし、ツールやリソースの呼び出し時にクエリが繰り返されるのを減らします。

パフォーマンスベンチマークを確認する

サーバーは、コア実行経路全体で毎秒数百万 ops を処理します。これにより、レイテンシーを最小限に抑え、スループットを最大化します。すべてのコンポーネントは、エンタープライズ規模のワークロード向けに調整されています。ミリ秒未満のサンドボックスコールドスタートと、最適化された逆引きをご活用ください。

ベンチマークの基準値：

• parseToolFilter：毎秒約32,000～62,000 ops
• CodeModeSandbox.create のコールドスタート：毎秒約2.78M ops
• Sandbox の破棄：毎秒約2.37M ops
• SandboxPool の初期化：毎秒約109k ops
• Set.has によるツール確認：毎秒約4.4M ops
• Map.get による逆引き：毎秒約4.5M ops
• Map.get による URI の照合：毎秒約5.1M ops
• validateCode の安全な短い入力：毎秒約173k ops
• validateCode のブロック対象入力：毎秒約298k ops
• checkRateLimit：毎秒約205k ops
• sanitizeResult の小さなペイロード：毎秒約1.49M ops
• プロンプトスキーマの解析：毎秒約1.3M ops

ヒント： 開発時は METADATA_CACHE_TTL_MS を小さくしてください（例：5000）。スキーマが安定している本番環境では、大きくしてください（例：300000 = 5分）。

ペイロードの最適化： ツールは summary: true と limit パラメーターをサポートしています。これらを使うと、大きなペイロードを簡潔にできます。

---

🎛️ サーバー設定を管理する

CLI オプションを設定する

注： CLI フラグの列で — が付いている項目は、環境変数でのみ設定できます。 | オプション | 環境変数 | 説明 | | ------------------------- | ----------------------- | --------------------------------------------------- | | --config, -c | — | 設定ファイルのパス（.yaml または .json） | | --dump-config | — | 現在の設定を標準出力に出力して終了 | | --version, -v | — | バージョン番号を表示 | | --help, -h | — | ヘルプを表示 | | --json | — | JSON 形式で出力 | | --transport, -t | — | トランスポートの種類：stdio、http、sse（デフォルト：stdio） | | --port, -p | MYSQLMCP_PORT | http トランスポート用の HTTP ポート | | --server-host | MCP_HOST | HTTP トランスポートをバインドするホスト（デフォルト：localhost） | | --mysql, -m | — | MySQL 接続文字列 | | --mysql-host | MYSQL_HOST | MySQL ホスト | | --mysql-port | MYSQL_PORT | MySQL ポート | | --mysql-user | MYSQL_USER | MySQL ユーザー名 | | --mysql-password | MYSQL_PASSWORD | MySQL パスワード | | --mysql-database | MYSQL_DATABASE | MySQL データベース名 | | --pool-size | MYSQL_POOL_SIZE | 接続プールのサイズ（デフォルト：10） | | --pool-timeout | — | 接続取得のタイムアウト（ミリ秒、デフォルト：30000） | | --pool-queue-limit | — | 待機中のリクエストのキュー上限（デフォルト：0） | | --tool-filter, -f | TOOL_FILTER | ツールフィルター文字列 | | --name | — | サーバー名 | | --auth-token | MCP_AUTH_TOKEN | HTTP 認証用のシンプルなベアラートークン | | --stateless | — | ステートレス HTTP モードを有効化 | | --trust-proxy | TRUST_PROXY | クライアント IP の取得で X-Forwarded-For を信頼 | | --enable-hsts | MCP_ENABLE_HSTS | HTTP Strict Transport Security を有効化 | | --metrics-export | MCP_METRICS_EXPORT | メトリクスのエクスポート形式（例：prometheus） | | --log-level | LOG_LEVEL | ログレベル：debug、info、warn、error | | --allowed-io-roots | ALLOWED_IO_ROOTS | すべてのファイル I/O 操作で許可するパスの JSON 配列またはカンマ区切りリスト | | --audit-log | MCP_AUDIT_LOG | 監査ログを書き込むファイルパス（書き込み先） | | — | AUDIT_LOG_PATH | エクスポーターが監査ログを読み込むファイルパス（読み込み元） | | --audit-backup | — | 変更前スナップショットを有効化 | | --audit-reads | — | 読み取りスコープのツール呼び出しを監査ログに含める | | --audit-redact | — | 監査ログ内の機密性の高い引数をマスキングする | | --audit-log-max-size | — | ローテーション前の最大ファイルサイズ（バイト） | | --audit-backup-data | — | 変更前スナップショットにサンプルデータを含める | | --audit-backup-max-size | — | データ取得の対象となるテーブルの最大サイズ（バイト） | | --oauth-enabled, -o | OAUTH_ENABLED | OAuth 2.1 認証を有効化 | | --oauth-issuer | OAUTH_ISSUER | 認可サーバーの URL | | --oauth-audience | OAUTH_AUDIENCE | 想定されるトークンのオーディエンス | | --oauth-jwks-uri | OAUTH_JWKS_URI | JWKS URI（自動検出） | | --oauth-clock-tolerance | OAUTH_CLOCK_TOLERANCE | クロック許容誤差（秒） | | — | MYSQL_ROUTER_URL | MySQL Router の URL | | — | MYSQL_ROUTER_USER | MySQL Router のユーザー | | — | MYSQL_ROUTER_PASSWORD | MySQL Router のパスワード | | — | MYSQL_ROUTER_INSECURE | Router の TLS 検証をバイパス | | — | MYSQL_ROUTER_API_VERSION | MySQL Router REST API のバージョン（デフォルト：/api/20190715） | | — | PROXYSQL_HOST | ProxySQL ホスト | | — | PROXYSQL_PORT | ProxySQL ポート | | — | PROXYSQL_USER | ProxySQL ユーザー | | — | PROXYSQL_PASSWORD | ProxySQL パスワード | | — | MYSQLSH_PATH | MySQL Shell 実行可能ファイルのパス | | — | MYSQL_XPORT | MySQL X Protocol のポート（デフォルト 33060） | | — | CODEMODE_ISOLATION | Code Mode の分離レベル（V8 のメモリ制限と厳格さを制御） | | — | CODEMODE_MAX_RESULT_SIZE | Code Mode の結果ペイロードの最大サイズ（バイト） | | — | METADATA_CACHE_TTL_MS | スキーマメタデータのキャッシュ TTL | | — | REDIS_URL | Redis 接続 URL（レート制限に使用） | | — | MCP_RATE_LIMIT_MAX | IP ごとの 1 分あたりの HTTP リクエスト最大数（デフォルト 100） | | — | CODEMODE_RATE_LIMIT_MAX| 1 分あたりの Code Mode 実行最大数（デフォルト 60） | 優先順位： --auth-token と --oauth-enabled の両方が設定されている場合は、OAuth 2.1 が優先されます。どちらも設定されていない場合、サーバーは警告を表示し、認証なしで実行されます。

スコープを適用する

OAuth スコープの適用を参照してください。

📖 Keycloak のセットアップと詳細な設定については、OAuth Wikiを参照してください。

💻 貢献して開発を加速する

セットアップについては、上記の**ソースからビルド**を参照してください。クローンした後：

pnpm run lint
pnpm run typecheck
pnpm test
pnpm run test:e2e  # Run individually to avoid timeouts

MCP Inspector でデバッグする

M C P Inspectorを使用して、mysql-mcp を視覚的にテスト、デバッグできます。

まず、サーバーをビルドします：

pnpm run build

mysql-mcp で Inspector を起動します：

npx @modelcontextprotocol/inspector node dist/cli.js \
  --transport stdio \
  --mysql mysql://mcp_user:secure_password@localhost:3306/testdb

http://localhost:5173 を開くと、すべてのツール、リソース、プロンプトを対話的に確認できます。

スクリプト作成用の CLI モード：

すべてのツールを一覧表示します：

npx @modelcontextprotocol/inspector --cli node dist/cli.js \
  --transport stdio --mysql mysql://... \
  --method tools/list

特定のツールを呼び出します：

npx @modelcontextprotocol/inspector --cli node dist/cli.js \
  --transport stdio --mysql mysql://... \
  --method tools/call --tool-name mysql_list_tables

📖 詳しい使い方については、MCP Inspector Wikiを参照してください。

単体テストを実行する

このプロジェクトでは、Vitest を使用して高いテストカバレッジを維持しています。

pnpm test

カバレッジレポートを実行します：

pnpm run test:coverage

テストインフラストラクチャ：

• src/__tests__/mocks/ にモックファクトリーを集約
• 一貫性を保つため、すべてのテストファイルで共有モックを使用
• データベース接続なしでテストを実行（完全にモック化）
• 単体テストはモックを使用します。E2E テストとストレステストには、稼働中のデータベース接続が必要です。

ベンチマークを実行する

このプロジェクトには、パフォーマンスベンチマークスイートが含まれています。重要な処理経路の効率を測定します。対象には、Code Mode のサンドボックス初期化、ツールのフィルタリング、URI ルーティングが含まれます。

pnpm run bench

---

貢献ガイドライン • セキュリティポリシー • MIT ライセンス • 行動規範