mysql-mcp-server

Model Context Protocol (MCP) サーバーで、MCP クライアント（Claude Desktop、Claude Code など）が MySQL データベースに対して SQL を実行できるようにします。ツールは select、insert、update、delete の4つです。

このサーバーは uv 管理の Python パッケージとして動作し、クライアントが起動したサブプロセスとして stdio 経由でクライアントと通信します。

要件

• Python 3.11+

• uv

• 到達可能な MySQL サーバー

Related MCP server: Universal Database MCP Server

インストール

uv sync

設定

サーバーには6つの値が必要です。各値は環境変数および/または CLI フラグで設定できます（CLI フラグは環境変数より優先されます）:

必要な値が欠けている場合、または MYSQL_MODE が readonly/readwrite でない場合、サーバーは stderr にエラーを出力し、起動せずに終了コード1で終了します。

• readonly モード: select ツールのみが許可されます。insert/update/delete は PERMISSION_DENIED エラーで拒否されます。

• readwrite モード: 4つすべてのツールが許可されます。

モードはプロセスの存続期間中固定され、実行時に変更することはできません。

セキュリティ上の推奨事項: readonly モードはアプリケーションレベルの保護であり、データベース権限の代わりにはなりません。可能な場合は、readonly モードの接続先として SELECT 権限のみを持つ MySQL アカウントを使用してください。

.env ファイルは必要ですか？ いいえ。サーバー自体が .env ファイルを読み取ることはありません。読み取るのは CLI フラグと実際のプロセス環境変数（os.environ）だけです。その環境に値をどう渡すかは、実行方法によって異なります:

• MCP サーバーとして使用する場合（下記の MCP クライアントから接続する を参照）: クライアント（Claude Desktop/Code）がサーバープロセスを起動し、自身の JSON 設定の env ブロックを環境変数として直接注入します。.env ファイルは関与せず、必要もありません。

• ローカル開発・テスト用に CLI を直接実行する場合: .env は、6つの変数を手動で export しなくて済むようにするための便宜上のものです。.env.example を .env にコピーし、実際の値を入力して、明示的に読み込んでください。自動的に読み込まれることはありません:

  uv run --env-file .env mysql-mcp-server

  .env は git で無視され、決してコミットしてはなりません。

実行

# Environment variables (or use `uv run --env-file .env mysql-mcp-server`, see above)
export MYSQL_MODE=readonly
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=app_user
export MYSQL_PASSWORD=secret
export MYSQL_DATABASE=mydb
uv run mysql-mcp-server

# Or, equivalently, via CLI flags
uv run mysql-mcp-server \
  --mysql-mode readonly \
  --mysql-host 127.0.0.1 \
  --mysql-port 3306 \
  --mysql-user app_user \
  --mysql-password secret \
  --mysql-database mydb

MCP クライアントから接続する

Claude Desktop / Claude Code

MCP クライアントのサーバー設定にエントリを追加します（例: Claude Desktop の claude_desktop_config.json、Claude Code の場合は .mcp.json）:

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mysql-mcp-server",
        "run",
        "mysql-mcp-server"
      ],
      "env": {
        "MYSQL_MODE": "readonly",
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "app_user",
        "MYSQL_PASSWORD": "secret",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}

設定を編集したらクライアントを再起動してください。select、insert、update、delete ツールが（MYSQL_MODE に応じて）モデルで利用できるようになります。

ツール

4つのツールはすべて {"query": string, "params"?: array} を受け取り、query 内では常に %s パラメーターバインディングのプレースホルダーを使用します。ユーザー入力を文字列としてクエリにフォーマットすることは決してありません。

各ツール呼び出しは、次のいずれかを返します:

{ "success": true, "data": { ... } }

{ "success": false, "error": { "code": "...", "message": "..." } }

エラーコード: PERMISSION_DENIED、INVALID_QUERY_TYPE、MULTI_STATEMENT_NOT_ALLOWED、DB_CONNECTION_ERROR、DB_EXECUTION_ERROR、INTERNAL_ERROR。

マルチステートメントクエリ（; 区切り）および DDL・権限ステートメント（DROP、TRUNCATE、ALTER、GRANT、CREATE USER など）は常に拒否されます。受け付けられるのは、上記の許可された4種類のステートメントのみだからです。

開発

uv sync
uv run ruff format .
uv run ruff check .
uv run pytest -v
uv run uv build   # packaging check

トラブルシューティング

• サーバーが終了コード1で即座に終了する: 必要な MYSQL_* の値が欠けているか、MYSQL_MODE が無効です。どれが原因かは stderr を確認してください。

• DB_CONNECTION_ERROR: MySQL に到達できないか、認証情報が誤っています。サーバーは実行を継続し、次のツール呼び出し時に接続を再試行します。

• insert/update/delete での PERMISSION_DENIED: サーバーが readonly モードで実行されています。書き込みを行う場合は MYSQL_MODE=readwrite で再起動してください。

バージョン履歴

• 0.1.0 — 初期リリース: select/insert/update/delete ツール、readonly/readwrite モードポリシー、stdio MCP トランスポート、接続切断時の自動再接続・再試行。