MySQL Query MCP Server

MySQL Query MCP Server

AI アシスタント向けに読み取り専用の MySQL データベースクエリを提供する Model Context Protocol（MCP）サーバーです。AI 搭載ツールから直接クエリを実行し、データベース構造を調べ、データを調査できます。

対応 AI ツール

この MCP サーバーは、以下を含む Model Context Protocol 対応のあらゆるツールで動作します。

• Cursor IDE：.cursor/mcp.json で設定します
• Anthropic Claude：互換性のある MCP クライアントで使用します
• その他の MCP 対応 AI アシスタント：ツールの MCP 設定手順に従ってください

機能と制限

できること

• ✅ 読み取り専用の MySQL クエリを実行します（SELECT、SHOW、DESCRIBE のみ）
• ✅ 定義済みの環境（local、development、staging、production）で動作します
• ✅ データベース情報とメタデータを提供します
• ✅ 利用可能なデータベース環境を一覧表示します
• ✅ 安全なデータベース接続のために SSL 接続をサポートします
• ✅ 長時間実行される処理を防ぐため、クエリのタイムアウトを実装しています

できないこと

• ❌ 書き込み操作を実行します（INSERT、UPDATE、DELETE、CREATE、ALTER など）
• ❌ カスタム環境名をサポートします（local、development、staging、production に限定）
• ❌ データベース設計やスキーマ生成の機能を提供します
• ❌ 完全なデータベース管理ツールとして機能します

このツールは、読み取り専用クエリによるデータの調査と探索に特化して設計されています。データベース管理、スキーマ管理、データ変更を目的としたものではありません。

クイックインストール

# Install globally with npm
npm install -g mysql-query-mcp-server

# Or run directly with npx
npx mysql-query-mcp-server

セットアップ手順

MCP サーバーを使用するよう AI ツールを設定する

MCP 設定ファイルを作成または編集します（例：Cursor IDE の場合は .cursor/mcp.json）。

基本設定：

{
  "mysql": {
    "name": "MySQL Query MCP",
    "description": "MySQL read-only query access through MCP",
    "type": "bin", 
    "enabled": true,
    "bin": "mysql-query-mcp"
  }
}

データベース認証情報を含む詳細設定：

{
  "mysql": {
    "command": "npx",
    "args": ["mysql-query-mcp-server@latest"],
    "env": {
      "LOCAL_DB_HOST": "localhost",
      "LOCAL_DB_USER": "root",
      "LOCAL_DB_PASS": "<YOUR_LOCAL_DB_PASSWORD>",
      "LOCAL_DB_NAME": "your_database",
      "LOCAL_DB_PORT": "3306",
      
      "DEVELOPMENT_DB_HOST": "dev.example.com",
      "DEVELOPMENT_DB_USER": "<DEV_USER>",
      "DEVELOPMENT_DB_PASS": "<DEV_PASSWORD>",
      "DEVELOPMENT_DB_NAME": "your_database",
      "DEVELOPMENT_DB_PORT": "3306",
      
      "STAGING_DB_HOST": "staging.example.com",
      "STAGING_DB_USER": "<STAGING_USER>",
      "STAGING_DB_PASS": "<STAGING_PASSWORD>",
      "STAGING_DB_NAME": "your_database",
      "STAGING_DB_PORT": "3306",
      
      "PRODUCTION_DB_HOST": "prod.example.com",
      "PRODUCTION_DB_USER": "<PRODUCTION_USER>",
      "PRODUCTION_DB_PASS": "<PRODUCTION_PASSWORD>",
      "PRODUCTION_DB_NAME": "your_database",
      "PRODUCTION_DB_PORT": "3306",
      
      "DEBUG": "false",
      "MCP_MYSQL_SSL": "true",
      "MCP_MYSQL_REJECT_UNAUTHORIZED": "false",
      "MYSQL_TIMEZONE": "Z"
    }
  }
}

適切な設定方法を選ぶ

MySQL MCP サーバーの設定方法は 2 通りあります。

1. バイナリ設定（type: "bin"、bin: "mysql-query-mcp"）

   • 使用する場合：パッケージをグローバルにインストールした場合（npm install -g mysql-query-mcp-server）
   • メリット：設定が簡単です
   • デメリット：グローバルインストールが必要です

2. コマンド設定（command: "npx"、args: ["mysql-query-mcp-server@latest"]）

   • 使用する場合：グローバルにインストールせず、最新バージョンを使いたい場合
   • メリット：グローバルインストールが不要で、すべての設定を 1 つのファイルにまとめられます
   • デメリット：設定がより複雑です

ワークフローに最も適した方法を選んでください。どちらの方法も、MCP をサポートするあらゆる AI アシスタントで正しく動作します。

重要な設定上の注意事項

• 環境名は省略せずに使用する必要があります：LOCAL_、DEVELOPMENT_、STAGING_、PRODUCTION_
• DEV_ や PROD_ などの略称は機能しません
• DEBUG、MCP_MYSQL_SSL などのグローバル設定はすべての環境に適用されます
• 少なくとも 1 つの環境（通常は「local」）を設定する必要があります
• 使用する環境のみを設定すれば十分です
• セキュリティ上の理由から、本番環境の認証情報には環境変数または安全な認証情報ストレージの使用を検討してください
• DATETIME、DATE、TIMESTAMP 列は、ホストのタイムゾーンによるずれを避け、MySQL に保存された値を正確に保持するため、文字列として返されます

設定オプション

環境変数	説明	デフォルト
DEBUG	デバッグログを有効にします	false
[ENV]_DB_HOST	環境のデータベースホスト	-
[ENV]_DB_USER	データベースのユーザー名	-
[ENV]_DB_PASS	データベースのパスワード	-
[ENV]_DB_NAME	データベース名	-
[ENV]_DB_PORT	データベースのポート	3306
[ENV]_DB_SSL	SSL 接続を有効にします	false
MCP_MYSQL_SSL	すべての接続で SSL を有効にします	false
MCP_MYSQL_REJECT_UNAUTHORIZED	SSL 証明書を検証します	true
MYSQL_TIMEZONE	クエリで JavaScript Date 値を送信する際に mysql2 が使用するタイムゾーン	Z

日付と時刻の値

MySQL の DATETIME、DATE、TIMESTAMP カラムは、たとえば 2026-05-13 16:12:08 のように、生の文字列として返されます。これにより、保存された値がそのまま保持され、JSON シリアライズ時に Node のホストのタイムゾーンによって結果がずれるのを防ぎます。

MYSQL_TIMEZONE のデフォルトは Z（UTC）です。アプリケーションが異なる接続タイムゾーンを使用して JavaScript の Date オブジェクトを MySQL に意図的に送信する場合にのみ、値を上書きしてください。

日付と時刻の値を文字列としてすでに処理している呼び出し元は、変更する必要はありません。この MCP サーバーから以前は JavaScript の Date オブジェクトが返されることを想定していた呼び出し元は、返された文字列を明示的に解析してください。

AI アシスタントとの連携

AI アシスタントは、MCP サーバーを通じて MySQL データベースとやり取りできます。以下に例を示します。

クエリの例：

Can you use the query tool to show me the first 10 users from the database? Use the local environment.

I need to analyze our sales data. Can you run a SQL query to get the total sales per region for last month from the development database?

Can you use the info tool to check what tables are available in the staging database?

Can you list all the available database environments we have configured?

MySQL MCP ツールの使用

MySQL Query MCP サーバーには、AI アシスタントが使用できる主なツールが 3 つあります。

1. query

特定の環境に対して読み取り専用 SQL クエリを実行します：

Use the query tool to run:
SELECT * FROM customers WHERE signup_date > '2023-01-01' LIMIT 10;
on the development environment

2. info

データベースの詳細情報を取得します：

Use the info tool to check the status of our production database.

3. environments

設定から構成済みの環境をすべて一覧表示します：

Use the environments tool to show me which database environments are available.

利用可能なツール

MySQL Query MCP サーバーには、主なツールが 3 つあります：

1. query

読み取り専用 SQL クエリを実行します：

-- Example query to run with the query tool
SELECT * FROM users LIMIT 10;

サポートされるクエリタイプ（以下に厳密に限定）：

• SELECT 文
• SHOW コマンド
• テーブルの DESCRIBE/DESC

2. info

データベースの詳細情報を取得します：

• サーバーバージョン
• 接続状態と稼働時間
• 選択されたサーバー変数（文字セット、タイムゾーン、タイムアウト、接続上限）
• 接続カウンター（接続中のスレッド、実行中のスレッド、クエリ数）
• 利用可能なデータベース

SHOW VARIABLES の全出力とサーバーのプロセスリストは、意図的に報告されません。SECURITY.md を参照してください。

3. environments

設定から構成済みの環境をすべて一覧表示します：

Use the environments tool to show me which database environments are available.

セキュリティに関する考慮事項

• ✅ 読み取り専用クエリ（SELECT、SHOW、DESCRIBE）のみが許可されます
• ✅ 各環境には独立した接続プールがあります
• ✅ 本番環境では SSL 接続がサポートされています
• ✅ クエリのタイムアウトにより、処理が際限なく続くのを防ぎます
• ✅ ツールの応答に設定値は含まれず、返される前にシークレットが含まれていないか確認されます
• ⚠️ MCP クライアントの設定では、認証情報は引き続き平文の環境変数として設定されます。このファイルをバージョン管理の対象にしないでください

1.3.0 より前のバージョンを使用していた場合

1.2.2 までのバージョンでは、environments ツールの応答にデータベース認証情報が含まれていたため、AI チャットのトランスクリプトに記録された可能性があります。このサーバーで設定した認証情報をすべて変更してください。 詳細は SECURITY.md を参照してください。

トラブルシューティング

接続に関する問題

接続に問題がある場合：

1. MCP の設定でデータベース認証情報を確認します
2. MySQL サーバーが稼働しており、アクセス可能であることを確認します
3. 接続をブロックしているファイアウォールルールがないか確認します
4. 設定で DEBUG=true を指定してデバッグモードを有効にします

よくあるエラー

エラー：環境に利用可能な接続プールがありません

• その環境に必要な環境変数がすべて定義されていることを確認してください
• サポートされている環境名（local、development、staging、production）のいずれかを使用していることを確認してください

エラー：クエリの実行に失敗しました

• SQL の構文を確認してください
• サポートされているクエリタイプ（SELECT、SHOW、DESCRIBE）のみを使用していることを確認してください
• クエリが確実に読み取り専用であることを確認してください

より詳しいトラブルシューティングについては、トラブルシューティングガイドを参照してください。

AI アシスタントとの連携例については、連携例を参照してください。

MCP プロトコルの実装の詳細については、MCP READMEを参照してください。

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

CI/CD とリリースプロセス

このプロジェクトでは、継続的インテグレーションと自動リリースに GitHub Actions を使用しています。

CI/CD ワークフロー

CI/CD パイプラインは次の要素で構成されています。

1. ビルドとテスト：main ブランチと develop ブランチへのプッシュ時、およびこれらのブランチを対象とするプルリクエストで実行されます

   • Node.js 16.x および 18.x でコードベースをテストします
   • パッケージが正しくビルドされることを確認します
   • すべてのテストに合格することを検証します

2. リリース：変更が main ブランチにプッシュされ、ビルド／テストジョブが成功したときに実行されます

   • release-please を使用して、バージョンの更新と変更履歴の更新を管理します
   • Conventional Commits に基づくバージョン変更を含むリリース PR を作成します
   • リリース PR がマージされると、npm に自動で公開します

リリースプロセス

このプロジェクトではセマンティックバージョニングに従います。

• メジャーバージョン：破壊的変更（後方互換性のない変更）
• マイナーバージョン：新機能（後方互換性あり）
• パッチバージョン：バグ修正と軽微な改善

コミットはConventional Commits形式に従ってください。

• feat: add new feature - マイナーバージョンを更新
• fix: resolve bug - パッチバージョンを更新
• docs: update documentation - バージョンを更新しない
• chore: update dependencies - バージョンを更新しない
• BREAKING CHANGE: change API - メジャーバージョンを更新

main にプッシュすると、release-please がコミットを分析し、適切なバージョン更新と変更履歴の項目を含むリリース PR を自動で作成または更新します。

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細については、LICENSE ファイルを参照してください。

作者

Abou Koné - エンジニアリングリーダー兼 CTO

---

詳細情報やサポートについては、GitHub リポジトリでイシューを作成してください。