MCP MySQL Server

MCP MySQL サーバー

MCP MySQL Server は、MySQL データベースとの連携機能を提供する Go ベースの MCP サーバー実装です。MCP クライアント（Claude Desktop など）からデータベース操作を実行できます。

機能

• MCP 準拠：MCP 仕様に従い、ツールを実行するための JSON‐RPC ベースのインターフェイスを提供します。
• MySQL 操作：クエリ、スキーマの確認、（任意で）データ操作などのデータベース操作に対応しています。
• 読み取り専用モード：データ変更操作を防ぐための制限を任意で設定できます。
• クエリプランの検証：クエリの安全性を確認するため、EXPLAIN による分析を任意で実行できます。
• URL 形式の接続文字列：mysql://user:pass@host:port/dbname のような標準的な URL 形式のデータベース接続文字列に対応しています。
• 最小構成のコンテナー：Google の distroless を使用して構築されており、セキュリティが向上し、イメージサイズが小さくなっています。

要件

• Docker（推奨）

ローカル開発の場合：

• Go 1.24 以降
• MySQL サーバー（ローカルまたはリモート）

Docker を使用する（推奨）

# Pull the image
docker pull cnosuke/mcp-mysql:latest

# Run with default settings
docker run -i --rm cnosuke/mcp-mysql:latest

# Run with custom MySQL connection
docker run -i --rm \
  -e MYSQL_HOST=your-mysql-host \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=your-username \
  -e MYSQL_PASSWORD=your-password \
  -e MYSQL_DATABASE=your-database \
  cnosuke/mcp-mysql:latest

# Run in read-only mode
docker run -i --rm \
  -e MYSQL_HOST=your-mysql-host \
  -e MYSQL_USER=your-username \
  -e MYSQL_PASSWORD=your-password \
  -e MYSQL_DATABASE=your-database \
  -e MYSQL_READ_ONLY=true \
  cnosuke/mcp-mysql:latest

Claude Desktop で使用する（Docker）

Docker を使用して Claude Desktop と連携するには、claude_desktop_config.json ファイルにエントリーを追加します。

{
  "mcpServers": {
    "mysql": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "cnosuke/mcp-mysql:latest"],
      "env": {
        "MYSQL_HOST": "your-mysql-host",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your-username",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database",
        "MYSQL_READ_ONLY": "false"
      }
    }
  }
}

ビルドと実行（Go バイナリ）

または、Go バイナリを直接ビルドして実行できます。

# Build the server
make

# Run the server
./bin/mcp-mysql server --config=config.yml

Claude Desktop で使用する（Go バイナリ）

Go バイナリを使用して Claude Desktop と連携するには、claude_desktop_config.json ファイルにエントリーを追加します。

{
  "mcpServers": {
    "mysql": {
      "command": "./bin/mcp-mysql",
      "args": ["server"],
      "env": {
        "LOG_PATH": "mcp-mysql.log",
        "DEBUG": "false",
        "MYSQL_HOST": "your-mysql-host",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your-username",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database",
        "MYSQL_READ_ONLY": "false"
      }
    }
  }
}

Docker イメージの詳細

このプロジェクトでは、最終的な Docker イメージに Google の distroless コンテナーイメージを使用しています。ベースイメージの gcr.io/distroless/static には、次の特長があります。

• 攻撃対象領域の最小化：必要なコンポーネントのみが含まれます。
• イメージサイズの縮小：シェル、パッケージマネージャー、その他不要なバイナリは含まれません。
• セキュリティの向上：潜在的な脆弱性の数が減少します。

Docker イメージは、マルチステージビルドプロセスを使用して構築されます。

1. 最初のステージでは Go Alpine を使用してアプリケーションをビルドします。
2. 2 番目のステージでは distroless/static を使用し、コンパイル済みバイナリのみを含めます。

設定

サーバーは YAML ファイル（デフォルト：config.yml）または環境変数で設定します。

log: 'path/to/mcp-mysql.log' # Log file path, if empty no log will be produced
debug: false # Enable debug mode for verbose logging

mysql:
  host: 'localhost'
  user: 'root'
  password: ''
  port: 3306
  database: ''
  dsn: ''
  read_only: false
  explain_check: false

接続オプション

MySQL の接続情報は、次の 3 つの方法で指定できます（優先順位の高い順）。

1. ツールのパラメーター：ツールの呼び出し時に、dsn パラメーターを直接渡します。
2. 設定ファイル内の DSN：設定ファイルで mysql.dsn の値を設定します。
3. 個別のパラメーター：設定ファイルで接続パラメーターを個別に設定します。

いずれの方法でも接続情報が指定されていない場合、サーバーは接続情報を指定するよう促すエラーメッセージを返します。

設定オプション

• mysql.host：MySQL サーバーのホスト名（デフォルト：'localhost'）
• mysql.user：MySQL のユーザー名（デフォルト：'root'）
• mysql.password：MySQL のパスワード
• mysql.port：MySQL のポート（デフォルト：3306）
• mysql.database：MySQL のデータベース名
• mysql.dsn：MySQL の DSN（Data Source Name）文字列。指定すると、個別の接続パラメーターより優先されます。
• mysql.read_only：読み取り専用モードを有効にします。このモードでは、list、read_、desc_ で始まるツールのみが使用できます。
• mysql.explain_check：実行前に EXPLAIN でクエリプランを確認します。

環境変数を使用して設定を上書きできます。

• LOG_PATH：ログファイルのパス
• DEBUG：デバッグモードを有効にします（true/false）
• MYSQL_HOST：MySQL サーバーのホスト名
• MYSQL_PORT：MySQL サーバーのポート
• MYSQL_USER：MySQL のユーザー名
• MYSQL_PASSWORD：MySQL のパスワード
• MYSQL_DATABASE：MySQL のデータベース名
• MYSQL_DSN：MySQL の DSN 文字列
• MYSQL_READ_ONLY：読み取り専用モードを有効にします（true/false）
• MYSQL_EXPLAIN_CHECK：クエリプランの確認を有効にします（true/false）

ログ

ログの動作は設定で制御します。

• 設定ファイルで log が指定されている場合、ログは指定されたファイルに書き込まれます。
• log が空の場合、ログは出力されません。
• より詳細なログを出力するには、debug: true を設定します。

MCP サーバーのツール

MCP クライアントは、さまざまなツールを実行するために JSON‐RPC リクエストを送信してサーバーとやり取りします。以下の MCP ツールがサポートされています。

スキーマツール

1. list_database

   • MySQL サーバー内のすべてのデータベースを一覧表示します。
   • パラメーター：
     • dsn（任意）：設定を上書きする MySQL DSN 文字列。
   • 戻り値：該当するデータベース名の一覧。

2. list_table

   • MySQL サーバー内のすべてのテーブルを一覧表示します。
   • パラメーター：
     • dsn（任意）：設定を上書きする MySQL DSN 文字列。
   • 戻り値：該当するテーブル名の一覧。

3. create_table（読み取り専用モードでは利用できません）

   • MySQL サーバーに新しいテーブルを作成します。
   • パラメーター：
     • query：テーブルを作成する SQL クエリ。
     • dsn（任意）：設定を上書きする MySQL DSN 文字列。
   • 戻り値：影響を受けた行数。

4. alter_table（読み取り専用モードでは利用できません）

   • MySQL サーバー内の既存のテーブルを変更します。LLM には既存のテーブルやカラムを削除しないよう指示されます。
   • パラメーター：
     • query：テーブルを変更する SQL クエリ。
     • dsn（任意）：設定を上書きする MySQL DSN 文字列。
   • 戻り値：影響を受けた行数。

5. desc_table

   • テーブルの構造を説明します。
   • パラメーター：
     • name：説明するテーブルの名前。
     • dsn（任意）：設定を上書きする MySQL DSN 文字列。
   • 戻り値：テーブルの構造。

データツール

1. read_query

   • 読み取り専用の SQL クエリを実行します。
   • パラメーター：
     • query：実行する SQL クエリ。
     • dsn（任意）：設定を上書きする MySQL DSN 文字列。
   • 戻り値：クエリの実行結果。

2. write_query（読み取り専用モードでは利用できません）

   • 書き込み SQL クエリを実行します。
   • パラメーター：
     • query：実行する SQL クエリ。
     • dsn（任意）：設定を上書きする MySQL DSN 文字列。
   • 戻り値：影響を受けた行数、最後に挿入された ID：<last_insert_id>。

3. update_query（読み取り専用モードでは利用できません）

   • 更新 SQL クエリを実行します。
   • パラメーター：
     • query：実行する SQL クエリ。
     • dsn（任意）：設定を上書きする MySQL DSN 文字列。
   • 戻り値：影響を受けた行数。

4. delete_query（読み取り専用モードでは利用できません）

   • 削除 SQL クエリを実行します。
   • パラメーター：
     • query：実行する SQL クエリ。
     • dsn（任意）：設定を上書きする MySQL DSN 文字列。
   • 戻り値：影響を受けた行数。

MySQL DSN の形式

dsn パラメーターまたは mysql.dsn 設定オプションは、次の 2 つの形式で指定できます。

1. MySQL ネイティブ DSN 形式

[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...&paramN=valueN]

例：username:password@tcp(localhost:3306)/mydb?parseTime=true&loc=Local

この形式の詳細については、MySQL DSNを参照してください。

2. URL 形式の接続文字列

mysql://username:password@hostname:port/dbname?param1=value1&param2=value2

例：mysql://root:pass@localhost:3306/mydb?parseTime=true&loc=Local

この URL 形式は、MySQL ネイティブ DSN 形式に自動的に変換されます。 サポートされている URL スキーム：mysql://、mariadb://。

コマンドラインパラメーター

サーバーの起動時に、さまざまな設定を指定できます。

./bin/mcp-mysql server [options]

オプション：

• --config、-c：設定ファイルへのパス（デフォルト：「config.yml」）。

コントリビューション

コントリビューションを歓迎します！リポジトリをフォークし、改善やバグ修正のプルリクエストを送信してください。大きな変更を行う場合は、まずイシューを作成してアイデアについて話し合ってください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。

作者：cnosuke（x.com/cnosuke）