MySQL MCP Server

MySQL MCP Server

MySQL データベースとの安全なやり取りを可能にする Model Context Protocol（MCP）の実装です。このサーバーコンポーネントは、AI アプリケーション（ホスト／クライアント）と MySQL データベース間の通信を仲介し、制御されたインターフェースを通じて、データベースの探索や分析をより安全かつ体系的に行えるようにします。

注：MySQL MCP Server は、標準入出力（STDIO）と Streamable HTTP（SSE）の両方のトランスポートモードに対応しています。リモート／セルフホスト可能な環境へのデプロイには、SSE モードを推奨します。

デプロイオプション

• ホスト型 — Fronteir AI がサーバーを実行するため、ローカルでのセットアップは不要です。
• ローカル — Smithery がご自身のマシンにサーバーをインストールして実行します。

機能

• 利用可能な MySQL テーブルをリソースとして一覧表示
• テーブルの内容を読み取り
• 適切なエラー処理を伴う SQL クエリの実行
• マルチデータベースモード（オプションの MYSQL_DATABASE）
• SSE／HTTP トランスポート対応（MCP_TRANSPORT=sse）
• SSH トンネリング対応
• 包括的なスキーマ情報
• テーブルデータのサンプリング
• 環境変数による安全なデータベースアクセス
• 包括的なログ記録

インストール

手動インストール

pip install mysql-mcp-server

Smithery 経由でのインストール

Smithery 経由で Claude Desktop 用の MySQL MCP Server を自動的にインストールするには：

npx -y @smithery/cli install designcomputer/mysql-mcp-server --client claude

Claude Code CLI 経由でのインストール

claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server

Autohand Code CLI 経由でのインストール

autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server

登録を現在のワークスペース内に保持するには、mcp add の後に --scope project を追加してください。CLI の最新情報については、Autohand Code を参照してください。

設定

次の環境変数を設定してください：

MYSQL_HOST=localhost     # Database host
MYSQL_PORT=3306         # Optional: Database port (defaults to 3306 if not specified)
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # Optional: Omit for multi-database mode

# Advanced Configuration
MYSQL_SSL_MODE=DISABLED  # DISABLED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # Timeout in seconds

# Connection behaviour (Optional)
MYSQL_SQL_MODE=TRADITIONAL           # SQL mode applied to the connection (default: TRADITIONAL)

# Compatibility (Optional)
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # e.g., mysql_native_password for older MySQL versions
MYSQL_USE_PURE=false     # Force the pure-Python connector (default: false)
MYSQL_RAISE_ON_WARNINGS=false        # Raise on SQL warnings (default: false)

# SSE Transport (Optional)
MCP_TRANSPORT=stdio      # stdio or sse
MCP_SSE_HOST=0.0.0.0     # Listen on all interfaces (required for Docker/hosting)
PORT=8000                # HTTP port (fallback for MCP_SSE_PORT)
MCP_SSE_ALLOWED_HOSTS=   # Comma-separated allowed Host headers (default: localhost:{port},127.0.0.1:{port})

# SSH Tunneling (Optional)
MYSQL_SSH_ENABLE=false   # Set to true to enable
MYSQL_SSH_HOST=          # SSH jump host
MYSQL_SSH_PORT=22        # SSH port
MYSQL_SSH_USER=          # SSH username
MYSQL_SSH_KEY_PATH=      # Path to SSH private key
MYSQL_SSH_REMOTE_HOST=localhost # Host from the perspective of the jump host
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

.env ファイルの読み込み

起動時に、サーバーは python-dotenv を使って .env ファイルを自動的に読み込みます。そのため、ローカルで使用する場合は、次のようにするだけです：

cp .env.example .env   # then edit with your credentials

ファイルは プロセスの作業ディレクトリ（および親ディレクトリ）から読み込まれます。プロジェクトフォルダーからサーバーを直接実行する場合に利用できます。

⚠️ **Claude Code／Claude Desktop：**これらのホストは独自の作業ディレクトリからサーバーを起動するため、プロジェクトの .env は見つからず、Missing required database configuration が表示されます。.env に頼るのではなく、MCP 設定の env ブロック（下記の「使用方法」セクションを参照）に MYSQL_* の値を指定してください。

マルチデータベースモード

MYSQL_DATABASE が設定されていない場合、サーバーはマルチデータベースモードで動作します：

• list_resources はすべてのユーザーデータベースを返します（システムデータベースは除外されます）
• SQL クエリでは mydb.mytable のような完全修飾テーブル名を使用してください
• **注：**サポートされるのは単一の SQL 文のみです。複数文のクエリ（例：USE db; SELECT ...）には対応していません。

利用可能なツール

execute_sql

標準的な SQL クエリを実行します。

• 引数：query（文字列）
• 機能：SELECT、SHOW、DESCRIBE および DML（INSERT、UPDATE、DELETE）に対応しています。DML 操作には破壊的操作を示すヒントが付けられます。
• **制限：**単一の文のみ対応しています。複数文のクエリには対応していません。
• データベース間のクエリ：MYSQL_DATABASE の設定にかかわらず、任意のデータベースにクエリするには database.table 形式を使用してください。

get_schema_info

データベース構造の詳細なメタデータを提供します。

• 引数: table_name（任意の文字列）
• 出力: 列名、型、NULL 許容性、デフォルト値、コメント。
• 複数データベース: MYSQL_DATABASE 以外のテーブルを照会するには、database.table を渡します。テーブル名のみを指定すると、設定済みのデータベースが使用されます。
• 識別子のルール: 名前には英数字、アンダースコア、$ のみを使用できます（データベース名とテーブル名の区切りとしてドットを使用できます）。

get_table_sample

データの代表的なサンプルを取得します。

• 引数: table_name（文字列）、limit（任意の整数、最大 20）
• 使用例: 大量の結果を取得せずに、データ形式と内容をすばやく把握できます。
• 複数データベース: MYSQL_DATABASE 以外のテーブルのサンプルを取得するには、database.table を渡します。テーブル名のみを指定すると、設定済みのデータベースが使用されます。
• 識別子のルール: 名前には英数字、アンダースコア、$ のみを使用できます（データベース名とテーブル名の区切りとしてドットを使用できます）。

利用可能なプロンプト

ツールに加えて、サーバーは MCP プロンプト（クライアントが必要に応じて起動できる、ガイド付きの複数ステップのワークフロー）を公開します。Claude Code ではスラッシュコマンド（/mcp__<server>__<prompt>）として、Claude Desktop ではプロンプトの（+）メニューに表示されます。

プロンプト	引数	説明
explore_database	(なし)	データベースを体系的に調査します。利用可能なテーブルを見つけ、スキーマを確認し、データのサンプルを取得して、内容を要約します。
analyze_table	table_name (必須)	特定のテーブルを詳しく調査します。スキーマを取得し、データのサンプルを取得して、有用なクエリを提案します。データベースをまたいで検索する場合は、database.table 表記を使用できます。

例（Claude Code）：

/mcp__mysql__explore_database
/mcp__mysql__analyze_table customers

どちらのプロンプトも既存の get_schema_info ツールと get_table_sample ツールを連携させます。explore_database はテーブルの一覧を取得するために、リソース一覧も使用します。

使用方法

Claude Desktop の場合

claude_desktop_config.json に以下を追加します。

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mysql_mcp_server",
        "run",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

詳しい例やエージェント固有のガイダンスについては、MCP_USECASES.md を参照してください。

Visual Studio Code の場合

mcp.json に以下を追加します。

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mysql-mcp-server",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

注：動作させるには uv をインストールする必要があります。

MCP Inspector によるデバッグ

MySQL MCP Server は単独で実行したり、Python を使ってコマンドラインから直接実行したりすることを想定していませんが、デバッグには MCP Inspector を使用できます。

MCP Inspector を使うと、MCP の実装を簡単にテストおよびデバッグできます。

# Install dependencies
pip install -r requirements.txt
# Use the MCP Inspector for debugging (do not run directly with Python)

MySQL MCP Server は Claude Desktop などの AI アプリケーションに統合するように設計されており、単独の Python プログラムとして直接実行するものではありません。

開発

# Clone the repository
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
# Install development dependencies
pip install -r requirements-dev.txt
# Copy the example config and edit with your credentials
cp .env.example .env
# Edit .env with your MySQL connection details
# Run tests
pytest

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

• 識別子の検証: get_schema_info と get_table_sample に渡されるテーブル名とデータベース名は、厳格な許可リスト（英数字、アンダースコア、$ のみ。database.table の区切りとしてドットを 1 つ使用可能）に照らして検証されます。SQL インジェクションを防ぐため、その他の特殊文字は拒否されます。

• 暗号化されたアクセス: 安全なリモート接続のための SSL/TLS と SSH トンネリングを全面的にサポートします。

• ログのプライバシー: パスワードと SSH 秘密鍵はサーバーログ内で自動的にマスキングされます。

• 最小権限: 必要最小限の権限を付与した専用の MySQL ユーザーを必ず使用してください。

• SSE トランスポートには認証機能が組み込まれていません。 SSE サーバーはデフォルトで 0.0.0.0 にバインドされ、認証情報なしで接続を受け入れます。ローカルホストの範囲を超えて公開する場合は、認証を適用するリバースプロキシ（nginx、Caddy、Traefik）の背後に配置してください。nginx と HTTP Basic Auth を使った例：

  location /sse {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
      proxy_buffering off;
  }
  location /messages/ {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
  }
  

サーバーがループバックのみで待ち受け、プロキシだけが外部からアクセスできるように、MCP_SSE_HOST=127.0.0.1 を設定します。プロキシが転送する公開ホスト名を MCP_SSE_ALLOWED_HOSTS に設定します（例：MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443）。

デプロイを保護するための包括的なガイドについては、SECURITY.md を参照してください。

セキュリティのベストプラクティス

この MCP 実装が機能するには、データベースへのアクセスが必要です。セキュリティを確保するため、次の点にご注意ください。

1. 最小限の権限を持つ専用の MySQL ユーザーを作成します
2. root の認証情報や管理者アカウントは使用しないでください
3. データベースへのアクセスを必要な操作のみに制限します
4. 監査のためにロギングを有効にします
5. データベースへのアクセスを定期的にセキュリティレビューします

詳しい手順については、MySQL セキュリティ設定ガイドをご覧ください。

• 制限付きの MySQL ユーザーを作成する
• 適切な権限を設定する
• データベースへのアクセスを監視する
• セキュリティのベストプラクティス

⚠️ IMPORTANT: データベースへのアクセスを設定する際は、常に最小権限の原則に従ってください。

ライセンス

MIT ライセンスです。詳細については LICENSE ファイルをご覧ください。

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します