mysql

MySQL MCP サーバー

MySQL データベース向けの高品質な Model Context Protocol（MCP）サーバー実装です。このサーバーを使用すると、Claude などの AI アシスタントが標準化されたプロトコルを通じて MySQL データベースを操作できます。

バージョン：0.2.0 | プロトコル：MCP 2025-03-26 | Rust：1.70+ | ステータス：本番環境対応

目次

• 機能
• インストール
• クイックスタート（5 分）
• 使用方法
• 利用可能なツール
• データベースコンテキスト機能
• セキュリティに関する考慮事項
• アーキテクチャ
• トラブルシューティング
• 開発
• デプロイガイド
• 貢献
• ライセンス
• サポート

機能

• スキーマの検査：テーブルのスキーマと構造情報を取得します
• クエリの実行：SQL クエリを実行します（安全のため、デフォルトでは読み取り専用です）
• データ操作：挿入、更新、削除を行います
• データベースコンテキスト：クエリごとに使用するデータベースを指定します
• 安全制御：危険な操作を防ぐクエリ制限を設定できます
• 接続管理：再試行ロジックとプーリングによる堅牢な接続処理を行います
• エラー処理：詳細なメッセージを含む包括的なエラー報告を行います
• JSON-RPC 2.0 プロトコル：stdio 経由で標準化された通信を行います

インストール

前提条件

• Rust 1.70+
• MySQL 5.7+ または MariaDB 10.2+
• MySQL データベースへのアクセス

ソースからビルドする

git clone <repository-url>
cd mcp-server-mysql
cargo build --release

コンパイルされたバイナリは target/release/mcp-server-mysql に生成されます。

リリースパッケージから

# Extract the package
tar -xzf mcp-server-mysql-v0.2.0-linux-x86_64.tar.gz

# Move binary to system path (optional)
sudo cp mcp-server-mysql /usr/local/bin/

# Verify installation
mcp-server-mysql --version

クイックスタート（5 分）

ステップ 1：サーバーをビルドする

cargo build --release

バイナリは target/release/mcp-server-mysql に生成されます。

ステップ 2：接続をテストする

./target/release/mcp-server-mysql \
  --host localhost \
  --username root \
  --password yourpassword \
  --database testdb

「MCP MySQL Server started and ready to accept connections」と表示されます。

ステップ 3：Claude Desktop を設定する

Claude Desktop の設定ファイルを編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

次の設定を追加します。

{
  "mcpServers": {
    "mysql": {
      "command": "/absolute/path/to/mcp-server-mysql",
      "args": [
        "--host", "localhost",
        "--port", "3306",
        "--username", "your_username",
        "--password", "your_password",
        "--database", "your_database"
      ]
    }
  }
}

セキュリティに関する注意：本番環境では、設定ファイルにパスワードを直接記述する代わりに、環境変数または安全なシークレット管理ソリューションの使用を検討してください。

ステップ 4：Claude Desktop を再起動する

Claude Desktop を完全に終了してから、再度開きます。MCP サーバーが接続されると、小さなハンマーアイコンが表示されます。

ステップ 5：試してみましょう！

Claude に次のように尋ねます。

• 「MySQL データベースにある users テーブルのスキーマを表示してくれますか？」
• 「データベースをクエリして、products テーブルの最初の 10 行を表示してください」
• 「データベースにはどんなテーブルがありますか？」

使用方法

コマンドライン引数

mcp-server-mysql \
  --host localhost \
  --port 3306 \
  --username your_username \
  --password your_password \
  --database your_database \
  --allow-dangerous-queries false

引数リファレンス

引数	説明	デフォルト	必須
--host	MySQL サーバーのホスト名	localhost	いいえ
--port	MySQL サーバーのポート	3306	いいえ
--username	MySQL のユーザー名	-	はい
--password	MySQL のパスワード	（空）	いいえ
--database	接続するデータベース名	-	はい
--allow-dangerous-queries	INSERT/UPDATE/DELETE クエリを許可します	false	いいえ

Claude Desktop の設定

Claude Desktop の設定ファイルに次の設定を追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mysql": {
      "command": "/path/to/mcp-server-mysql",
      "args": [
        "--host", "localhost",
        "--port", "3306",
        "--username", "your_username",
        "--password", "your_password",
        "--database", "your_database"
      ]
    }
  }
}

利用可能なツール

1. mysql（スキーマの検査）

テーブルのデータベーススキーマ情報を取得します。

パラメーター：

• table_name（string）：検査するテーブル名、またはすべてのテーブルスキーマを取得する場合は "all-tables"

例：

{
  "table_name": "users"
}

戻り値：

• カラム情報（名前、型、NULL 許容、デフォルト値、キー）
• インデックス情報
• テーブル制約

2. query（SQL の実行）

データベースで SQL クエリを実行します。

パラメーター：

• query（string）：実行する SQL クエリ
• database（string、任意）：このクエリで使用するデータベース名

例：

{
  "query": "SELECT * FROM users WHERE active = 1 LIMIT 10",
  "database": "my_database"
}

安全性：

• デフォルトでは、SELECT クエリのみが許可されます
• INSERT／UPDATE／DELETE を有効にするには、--allow-dangerous-queries フラグを使用します
• 明示的に有効にしない限り、危険なキーワードはブロックされます

3. insert（データの挿入）

指定したテーブルにデータを挿入します。

パラメーター：

• table_name（string）：テーブル名
• data（object）：列名と値のキーと値のペア

例：

{
  "table_name": "users",
  "data": {
    "username": "john_doe",
    "email": "[email protected]",
    "active": true
  }
}

戻り値： 最後に挿入した ID

4. update（データの更新）

条件に基づいて、指定したテーブルのデータを更新します。

パラメーター：

• table_name（string）：テーブル名
• data（object）：更新する列と値のキーと値のペア
• conditions（object）：WHERE 句に使用するキーと値のペア

例：

{
  "table_name": "users",
  "data": {
    "email": "[email protected]",
    "updated_at": "2024-01-15 10:30:00"
  },
  "conditions": {
    "id": 123
  }
}

戻り値： 影響を受けた行数

5. delete（データの削除）

条件に基づいて、指定したテーブルのデータを削除します。

パラメーター：

• table_name（string）：テーブル名
• conditions（object）：WHERE 句に使用するキーと値のペア

例：

{
  "table_name": "users",
  "conditions": {
    "id": 123
  }
}

戻り値： 影響を受けた行数

警告： すべての行が削除されないよう、必ず条件を指定してください！

データベースコンテキスト機能

問題点

以前は、クエリ間でデータベースコンテキストが維持されませんでした。

-- Query 1
USE dev_database;  -- Succeeds

-- Query 2 (new connection from pool)
SELECT * FROM my_table;  -- ❌ Fails: context was lost

解決策

各クエリで任意の database パラメーターを使用します。

{
  "query": "SELECT * FROM my_table",
  "database": "dev_database"
}

メリット

1. 明示的で明確：各クエリがどのデータベースを使用するかを正確に把握できます
2. 隠れた状態なし：各クエリは独立しています
3. 後方互換性：パラメーターを指定しない既存のクエリも引き続き動作します
4. 競合状態なし：各クエリは個別の接続を取得します
5. 簡単に使用可能：クエリ引数に "database": "name" を追加するだけです

使用例

データベースパラメーターを指定した基本的なクエリ

{
  "query": "SELECT * FROM crm_sites LIMIT 10",
  "database": "dev_smartConnect_za"
}

データベースパラメーターを指定しないクエリ（デフォルトを使用）

{
  "query": "SELECT * FROM users WHERE active = 1"
}

起動引数 --database で指定したデータベースを使用します。

同じセッションで複数のデータベースを使用

// Query database 1
{
  "query": "SELECT COUNT(*) FROM customers",
  "database": "production_db"
}

// Query database 2
{
  "query": "SELECT COUNT(*) FROM test_data",
  "database": "test_db"
}

変更前と変更後

変更前（完全修飾名が必要）：

SELECT * FROM dev_smartConnect_za.crm_sites
  JOIN dev_smartConnect_za.crm_orgs ON ...
WHERE dev_smartConnect_za.crm_sites.active = 1;

変更後（簡潔でシンプル）：

{
  "query": "SELECT * FROM crm_sites JOIN crm_orgs ON ... WHERE active = 1",
  "database": "dev_smartConnect_za"
}

よくあるシナリオ

シナリオ 1：単一データベースのプロジェクト

デフォルトのデータベースを設定し、パラメーターを省略します。

# Startup
--database my_project_db

# Query (no database parameter needed)
{
  "query": "SELECT * FROM users"
}

シナリオ 2：複数データベースのプロジェクト

各クエリでデータベースを指定します。

// Customer database
{ "query": "...", "database": "customers_db" }

// Orders database
{ "query": "...", "database": "orders_db" }

// Analytics database
{ "query": "...", "database": "analytics_db" }

エラー処理

エラーコード -32005：接続の取得に失敗しました

Cause: Connection pool exhausted
Solution: Retry after a moment

エラーコード -32006：データベースコンテキストの切り替えに失敗しました

Cause: Database doesn't exist or user lacks permissions
Solution: Verify database exists and user has access

ベストプラクティス

✅ 推奨事項

• 本番環境のクエリではデータベースを明示的に指定します
• クエリでは説明的なデータベース名を使用します
• SELECT DATABASE() でコンテキストを確認します
• 明確になるよう、データベースごとにクエリをまとめます

❌ 避けるべき事項

• 同じクエリ内で修飾名と非修飾名を混在させないでください
• データベースが維持されると想定せず、各クエリで指定してください
• 可能な場合は、データベース名に特殊文字を使用しないでください
• すべてのデータベースに対するユーザー権限の確認を忘れないでください

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

読み取り専用モード（デフォルト）

デフォルトでは、サーバーは読み取り専用モードで動作し、SELECT クエリのみを許可します。これにより、誤ったデータの変更や削除を防止できます。

危険なクエリモード

書き込み操作を有効にするには、--allow-dangerous-queries を使用します。

mcp-server-mysql --username user --password pass --database mydb --allow-dangerous-queries true

注意して使用してください！ 次の操作が有効になります。

• INSERT 文
• UPDATE 文
• DELETE 文
• その他、破壊的な影響を及ぼす可能性のある操作

SQL インジェクション対策

• テーブル名は、英数字とアンダースコアのみを含むよう検証されます
• すべてのデータ値は、プリペアドステートメントを使用してパラメーター化されます
• データベース名は、バッククォートを二重バッククォートに置き換えてエスケープされます
• 生の SQL を連結する処理は行われません

接続セキュリティ

• 標準の MySQL SSL/TLS 接続をサポートしています
• 接続文字列は安全に設定できます
• パスワードは環境変数で指定できます
• 権限を制限した専用のデータベースユーザーを使用することを検討してください

本番環境へのデプロイ時のセキュリティ

1. 専用のデータベースユーザーを使用する：

   CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'secure_password';
   GRANT SELECT ON your_database.* TO 'mcp_user'@'localhost';
   FLUSH PRIVILEGES;
   

2. 必要な場合にのみ書き込みアクセスを有効にする：

   --allow-dangerous-queries true  # Use with caution!
   

3. 環境変数を使用する（今後の機能強化）： 環境変数を読み取るシェルスクリプトでバイナリをラップすることを検討してください。

アーキテクチャ

システム概要

┌─────────────────────────────────────────────────────┐
│           MCP Client (e.g., Claude)                 │
│  Sends: {query, database}                           │
└────────────────────────┬────────────────────────────┘
                         │ JSON-RPC 2.0 (stdio)
                         ▼
┌─────────────────────────────────────────────────────┐
│      MCP MySQL Server (Rust)                        │
│                                                      │
│  execute_query(query, database, pool)               │
│  ├─ If database param:                              │
│  │  ├─ Acquire connection from pool                 │
│  │  ├─ Execute: USE `database`                      │
│  │  └─ Execute: [user's query]                      │
│  └─ Else:                                           │
│     └─ Execute query on pool (default database)     │
└────────────────────────┬────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│      MySQL Connection Pool (5 connections)          │
└────────────────────────┬────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│      MySQL/MariaDB Server                           │
└─────────────────────────────────────────────────────┘

シーケンス：データベースパラメーターを使用したクエリ

Client          MCP Server       Connection Pool      MySQL Server
  │                 │                    │                  │
  │  query +        │                    │                  │
  │  database       │                    │                  │
  ├────────────────>│                    │                  │
  │                 │                    │                  │
  │                 │ acquire()          │                  │
  │                 ├───────────────────>│                  │
  │                 │ <connection>       │                  │
  │                 │<───────────────────┤                  │
  │                 │                    │                  │
  │                 │ USE database       │                  │
  │                 ├────────────────────┼─────────────────>│
  │                 │ OK                 │                  │
  │                 │<────────────────────┼──────────────────┤
  │                 │                    │                  │
  │                 │ SELECT query       │                  │
  │                 ├────────────────────┼─────────────────>│
  │                 │ Results            │                  │
  │                 │<────────────────────┼──────────────────┤
  │                 │                    │                  │
  │                 │ release()          │                  │
  │                 ├───────────────────>│                  │
  │  Results        │                    │                  │
  │<────────────────┤                    │                  │

接続プール管理

Pool (5 connections)
┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐
│ C1 │ │ C2 │ │ C3 │ │ C4 │ │ C5 │
└────┘ └────┘ └────┘ └────┘ └────┘

Key Properties:
• Each query gets its own connection instance
• Database context is set per connection, per query
• No state persists between queries
• Fully thread-safe and concurrent

技術的な詳細

• プロトコルバージョン：MCP 2025-03-26
• トランスポート：stdio（JSON-RPC 2.0）
• コネクションプーリング：最大 5 接続
• 再試行ロジック：一時的な障害時に自動再接続
• パフォーマンスのオーバーヘッド：データベースパラメーターを使用するクエリあたり約 50～200 マイクロ秒

トラブルシューティング

接続の失敗

接続エラーが発生した場合：

1. MySQL が実行中か確認します：

   mysql -h localhost -u your_username -p
   

2. 認証情報を確認します：

   • ユーザー名とパスワードが正しいことを確認します
   • ユーザーが指定したデータベースにアクセスできることを確認します

3. ネットワークアクセスを確認します：

   • ホストとポートが正しいことを確認します
   • ファイアウォールが接続をブロックしていないことを確認します

4. サーバーログを確認します：

   • サーバーのログは stderr に出力されます
   • 詳細なエラーメッセージを確認します

よくあるエラー

「Database connection failed」

• MySQL サーバーが実行されていない可能性があります
• ホストまたはポートの設定が正しくありません
• ネットワーク接続に問題があります

「Only SELECT queries are allowed」

• 読み取り専用モードで書き込みクエリを実行しようとしています
• 書き込みアクセスが必要な場合は、--allow-dangerous-queries true を追加してください

「No database selected」

• 指定したデータベースが存在しません
• ユーザーがデータベースにアクセスできません
• SHOW DATABASES; を実行して、利用可能なデータベースを確認してください

「Table doesn't exist」

• 正しいデータベースに対してクエリを実行していることを確認してください
• 複数のデータベースを使用する場合は、database パラメーターを追加してください
• SELECT DATABASE() を使用して、現在のコンテキストを確認してください

「Failed to acquire connection」

• 接続プールが枯渇しています
• 少し待ってから再試行してください

Claude Desktop にツールが表示されない

1. バイナリへのパスが絶対パスであることを確認します（相対パスではありません）
2. Claude Desktop のログでエラーを確認します
3. Claude Desktop を完全に再起動します（単に再読み込みするだけではありません）
4. 手動で実行したときに、サーバープロセスがエラーなく起動することを確認します

開発

プロジェクト構成

mcp-server-mysql/
├── src/
│   ├── main.rs          # Main server implementation
│   ├── config.rs        # Configuration handling
│   ├── db.rs            # Database operations
│   ├── rpc.rs           # RPC protocol handling
│   └── server.rs        # Server initialization
├── tests/               # Test files
├── Cargo.toml           # Rust dependencies
├── Cargo.lock          # Locked dependency versions
└── README.md           # This file

開発用ビルド

cargo build
cargo run -- --help

テストの実行

cargo test

コード品質

# Format code
cargo fmt

# Run linter
cargo clippy

# Check for issues
cargo check

開発規約

このプロジェクトでは、Rust の標準的なベストプラクティスに従っています：

• コードのフォーマット：cargo fmt
• 静的解析：cargo clippy
• テスト：cargo test

デプロイガイド

クイックデプロイ

1. 接続をテストする

./mcp-server-mysql \
  --username your_user \
  --password your_pass \
  --database your_db

「MCP MySQL Server started」と表示されたら、Ctrl+C を押して終了します。

2. Claude Desktop を設定する

Claude の設定ファイルを編集し、サーバー設定を追加します（「クイックスタート」セクションを参照）。

3. Claude Desktop を再起動する

Claude Desktop を完全に終了してから再度開きます。

本番環境へのデプロイのヒント

パフォーマンス

• バイナリは --release フラグを指定して最適化されています
• コネクションプーリングが設定されています（最大 5 接続）
• 一時的な障害時の自動再試行ロジックを備えています

監視

サーバーログは stderr に出力されます。次のようにしてログを取得します：

./mcp-server-mysql --username user --password pass --database db 2>> server.log

ログレベル：

• INFO：接続イベント、ツール呼び出し
• DEBUG：クエリの詳細情報
• WARN：致命的ではない問題
• ERROR：失敗やエラー

Systemd サービス（任意）

長時間稼働するデプロイでは、/etc/systemd/system/mcp-mysql.service を作成します：

[Unit]
Description=MySQL MCP Server
After=network.target mysql.service

[Service]
Type=simple
User=mcp-user
ExecStart=/usr/local/bin/mcp-server-mysql --username mcp_user --password secret --database production
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

有効化して起動します：

sudo systemctl enable mcp-mysql
sudo systemctl start mcp-mysql
sudo systemctl status mcp-mysql

アップグレード

# Backup current version
cp /usr/local/bin/mcp-server-mysql /usr/local/bin/mcp-server-mysql.backup

# Replace with new version
cp mcp-server-mysql /usr/local/bin/

# Restart services
sudo systemctl restart mcp-mysql  # If using systemd
# Or restart Claude Desktop

ロールバック

# Restore previous version
cp /usr/local/bin/mcp-server-mysql.backup /usr/local/bin/mcp-server-mysql

# Or checkout previous git tag
git checkout v0.1.0
cargo build --release

貢献

貢献を歓迎します！以下を確認してください：

• コードが Rust のベストプラクティスに従っていること
• すべてのテストが成功すること
• ドキュメントが更新されていること
• コミットメッセージが明確で説明的であること

ライセンス

Apache-2.0

サポート

問題、質問、または貢献については、プロジェクトリポジトリで issue を作成してください。

---

バージョン: 0.2.0 | リリース日: 2025-01-XX | プロトコル: MCP 2025-03-26 | プラットフォーム: Linux x86_64 | ステータス: 本番環境対応済み ✅