YugabyteDB MCP Server

YugabyteDB MCP サーバー

YugabyteDB および PostgreSQL 用の MCP サーバーです。LLM（Claude Desktop、Cursor、Windsurf など）がスキーマを要約し、読み取り専用クエリを実行し、設定可能なガードレール層のもとで書き込みステートメントを実行できます。

機能

• summarize_database — スキーマのテーブル、列、行数を一覧表示します（読み取り専用）
• run_read_only_query — BEGIN READ ONLY 内で SELECT を実行します。結果は JSON として返されます（読み取り専用）
• run_write_query — ガードレールのブロックリストによって制御される INSERT/UPDATE/DELETE/MERGE/TRUNCATE/DDL（破壊的な操作のため、デフォルトでは無効です。--enable-write-query または YB_MCP_ENABLE_WRITE_QUERY=true で有効にできます）

多層防御として、書き込みツールには destructiveHint: true が注釈されているため、ガードレールでステートメントの実行が許可される場合でも、Claude Desktop は呼び出しごとに確認プロンプトを表示します。

セルフホスト型のリモートデプロイメント向けに、オプションで OAuth（AWS Cognito）と Origin ヘッダーの検証を利用できます。

前提条件

• Python 3.10+
• uv（推奨）または pip
• 接続可能な YugabyteDB または PostgreSQL データベース
• MCP クライアント（Claude Desktop、Cursor、Windsurf など）

インストール

エンドユーザーが利用する機会が多いと思われる順に、3 つのインストール方法を紹介します。

# uvx — no install at all; fetches and runs on demand. Handy for one-off use
# and also the form the MCPB Desktop extension uses internally.
uvx yugabytedb-mcp-server --help

# pipx — installs to an isolated venv, puts the script on $PATH.
pipx install yugabytedb-mcp-server

# uv tool — same idea, uv-managed.
uv tool install yugabytedb-mcp-server

# pip — system-level or current-venv install.
pip install yugabytedb-mcp-server

pipx／uv tool／pip のいずれかで永続的にインストールした後、次のコマンドで確認します。

yugabytedb-mcp --help
# or, equivalently:
yugabytedb-mcp-server --help

どちらのコンソールスクリプトも登録されており、同じエントリーポイントを指しています。 yugabytedb-mcp は短縮形で、yugabytedb-mcp-server はパッケージ名に一致する名前です。uvx はデフォルトでこちらを解決します。

プレリリースに関する注意：v2 がリリース候補版（例：2.0.0rc2）の間は、デフォルトのインストールでは取得されません。現時点では、明示的にバージョンを指定して（pipx install yugabytedb-mcp-server==2.0.0rc2）、または --pip-args='--pre' を付けてインストールしてください。2.0.0 の安定版が公開されると、この手順は不要になります。

ソースから開発する方法については、以下の開発を参照してください。

Configuration

環境変数	CLI フラグ	必須	説明
YUGABYTEDB_URL	--yugabytedb-url	はい	libpq 接続文字列（例：host=… port=5433 dbname=… user=… password=…）。
YB_MCP_TRANSPORT	--transport	いいえ	stdio（デフォルト）または http。
YB_MCP_STATELESS_HTTP	--stateless-http	いいえ	true にすると、ステートレスな Streamable-HTTP が有効になります。セルフホストのマルチレプリカデプロイメントに必要です。
YB_MCP_REQUIRE_WHERE_ON_UPDATE	--require-where-on-update	いいえ	WHERE 句のない UPDATE を拒否します。デフォルトは false です。
YB_MCP_REQUIRE_WHERE_ON_DELETE	--require-where-on-delete	いいえ	WHERE 句のない DELETE を拒否します。デフォルトは false です。
YB_MCP_ENABLE_WRITE_QUERY	--enable-write-query	いいえ	run_write_query ツールを有効にします。デフォルトは false（書き込みツールは無効）です。
MCP_AUTH_PROVIDER	--mcp-auth-provider	いいえ	cognito または oidc。認証を無効にするには未設定にします。OIDC/Cognito の設定全般とユーザーごとの ID マッピングについては、OIDC.md を参照してください。
MCP_HOST	--host	いいえ	HTTP トランスポートのバインド先ホスト。デフォルトは 127.0.0.1（ループバック）です。すべてのインターフェースで公開するには 0.0.0.0 を設定します。その場合、認証が必須になります（MCP_AUTH_PROVIDER を参照）。
MCP_BASE_URL	—	認証有効時	サーバーにアクセスできる公開ベース URL（例：https://mcp.example.com）。
MCP_ALLOWED_ORIGINS	—	いいえ	DNS リバインディング対策として許可する Origin 値のカンマ区切りリスト。大文字と小文字を区別しません（RFC 6454）。デフォルトは MCP_BASE_URL です。
MCP_ALLOW_UNAUTHENTICATED	—	いいえ	認証なしで、ループバック以外のホスト上で HTTP モードを実行するための回避設定です。開発時のみ使用してください。起動時に目立つ WARNING がログに出力されます。
YB_LOG_LEVEL	—	いいえ	yugabytedb-mcp ロガーファミリーのログレベル（デフォルトは INFO）。
YB_AWS_SSL_ROOT_CERT_SECRET_ARN	--yb-aws-ssl-root-cert-secret-arn	いいえ	YugabyteDB TLS ルート証明書を格納する AWS Secrets Manager シークレットの ARN。
YB_AWS_SSL_ROOT_CERT_KEY	--yb-aws-ssl-root-cert-key	いいえ	複数の証明書を格納するシークレット内の JSON キー。
YB_AWS_SSL_ROOT_CERT_SECRET_REGION	--yb-aws-ssl-root-cert-secret-region	いいえ	シークレットの AWS リージョン。
YB_SSL_ROOT_CERT_PATH	--yb-ssl-root-cert-path	いいえ	取得した証明書の書き込み先。デフォルトは /tmp/yb-root.crt です。

OIDC/Cognito 認証、ユーザーごとの SET ROLE マッピング、ID マップファイルの形式、/auth/login ショートカットについては、OIDC.md を参照してください。

初期設定用テンプレートは .env.example にあります。

クイックスタート — Claude Desktop

接続方法は 2 通りあります。1 つ目は uvx を使用し、インストールは不要で、uv のみが必要です。2 つ目は、すでに pipx install（または同等のコマンド）を実行し、yugabytedb-mcp スクリプトが $PATH にあることを前提とします。

オプション 1 — uvx を使用（インストール不要）：

{
  "mcpServers": {
    "yugabytedb": {
      "command": "uvx",
      "args": ["yugabytedb-mcp-server"],
      "env": {
        "YUGABYTEDB_URL": "host=… port=5433 dbname=… user=… password=…"
      }
    }
  }
}

オプション 2 — インストール済みスクリプトを使用：

pipx install yugabytedb-mcp-server（または uv tool install …）を実行した後：

{
  "mcpServers": {
    "yugabytedb": {
      "command": "yugabytedb-mcp",
      "env": {
        "YUGABYTEDB_URL": "host=… port=5433 dbname=… user=… password=…"
      }
    }
  }
}

claude_desktop_config.json の場所：

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

Claude Desktop を再起動します。3 つのツールが、タイトルとヒントバッジ付きで表示されます（読み取りツールには読み取り専用アイコンが付き、run_write_query を呼び出すたびに確認プロンプトが表示されます）。

公開済みバージョンが 2.0.0rc2 のみの間は、uvx のスニペットでは args に ["[email protected]"]（または ["--pre", "yugabytedb-mcp-server"]）が必要です。2.0.0 の安定版がリリースされたら、明示的なバージョン指定を削除してください。

その他の MCP クライアント

同じ方法は Cursor（Settings → MCP → Add a new global MCP server）および Windsurf（Settings → Cascade → MCP Servers → Add custom server）でも使えます。上記の uvx 形式またはインストール済みスクリプト形式のどちらかを使用してください。

HTTP モードのサーバーに対して MCP Inspector を使う場合：

YUGABYTEDB_URL="…" yugabytedb-mcp --transport http
# in another shell:
npx @modelcontextprotocol/inspector
# In the GUI: URL http://localhost:8000/mcp, transport Streamable-HTTP

ツール

ツール	タイトル	ヒント	機能
summarize_database(schema='public')	"データベーススキーマと行数を要約する"	readOnlyHint: true	schema 内のテーブルを、列と行数とともに一覧表示します
run_read_only_query(query)	"読み取り専用の SQL クエリを実行する"	readOnlyHint: true	クエリを BEGIN READ ONLY でラップし、行を JSON として返します
run_write_query(query)	"書き込み SQL クエリを実行する（ガードレール付き）"	destructiveHint: true	ガードレールのブロックリストに照らしてクエリを検証してから実行します。デフォルトでは無効です — --enable-write-query が必要です。

run_write_query のガードレール

次の種類のステートメントは、実行前に拒否されます。

• DROP DATABASE/SCHEMA、ALTER DATABASE、CREATE DATABASE
• ロール／権限操作：GRANT、REVOKE、CREATE/ALTER/DROP ROLE、CREATE/ALTER/DROP USER
• 所有者として実行される可能性があるストアドコード（SECURITY DEFINER）：CREATE FUNCTION、CREATE PROCEDURE、ALTER FUNCTION、ALTER PROCEDURE
• ファイルシステム／コード実行：COPY TO/FROM、LOAD、匿名の DO $$ … $$、CREATE EXTENSION
• サーバー設定：ALTER SYSTEM、RESET ALL
• 危険な組み込み関数：pg_sleep、pg_read_file、pg_write_file、lo_import、lo_export、dblink
• スキーマ分離：SET search_path、CREATE SCHEMA
• 複数のステートメントを含むクエリ（区切り文字のセミコロンがあるもの）
• psql のメタコマンド（\c、\d、\!）
• オプションで、WHERE 句のない UPDATE／DELETE

INSERT／UPDATE／DELETE／DDL の実行時間には、YB_MCP_STATEMENT_TIMEOUT_MS による上限があります（すべての書き込みに SET LOCAL statement_timeout が適用されます）。実行が終わらない INSERT … SELECT や大量の INSERT … VALUES は、静的な行数上限ではなくデータベースによって停止されます。

CREATE TABLE … AS SELECT と SELECT … INTO は、構造上は同様に上限のない行コピーですが、クエリからスナップショットを作成する一般的な方法のため、意図的に許可されています。

このリストは可能な限り網羅していますが、完全ではありません。destructiveHint: true が第 2 の防御策となります。

セルフホスト可能なリモートモード

複数ユーザーまたは共有環境でデプロイする場合は、Cognito OAuth（または汎用 OIDC）でアクセスを制御し、TLS を使用したリバースプロキシの背後でサーバーを Streamable HTTP として実行してください。プロバイダー設定、ユーザーごとの SET ROLE マッピング、ID マップファイル形式、/auth/login ショートカット、セキュリティガイダンスを含む完全なセットアップ手順は、OIDC.md にあります。

デフォルトでセキュア： 修正以降、HTTP モードはデフォルトで 127.0.0.1 にバインドされ、次の両方に該当する場合は起動を拒否します。

• バインドホストがループバック以外（MCP_HOST が 0.0.0.0 または特定のアドレスに設定されている）
• 認証プロバイダーが設定されていない（MCP_AUTH_PROVIDER が未設定）

共有環境／ネットワーク環境にデプロイする場合は、MCP_HOST=0.0.0.0 と MCP_AUTH_PROVIDER の両方を設定してください。

export MCP_HOST=0.0.0.0                # expose beyond loopback (default: 127.0.0.1)
export MCP_AUTH_PROVIDER=cognito
export MCP_BASE_URL=https://mcp.example.com
export COGNITO_USER_POOL_ID=us-west-2_XXXXXXXX
export COGNITO_AWS_REGION=us-west-2
export COGNITO_CLIENT_ID=…
export COGNITO_CLIENT_SECRET=…
export YUGABYTEDB_URL=…
export MCP_ALLOWED_ORIGINS=https://mcp.example.com,https://claude.ai

yugabytedb-mcp --transport http --stateless-http

0.0.0.0 で開発専用の認証なしの利用をする場合は、MCP_ALLOW_UNAUTHENTICATED=true を設定してください。サーバーは目立つ WARNING を表示して起動します。本番環境では使用しないでください。

動作：

• 有効な Bearer トークンなしで /mcp に送信されたリクエストは 401 を返します。
• 許可されていない Origin ヘッダーを含むリクエストは 403 を返します（DNS リバインディング対策）。
• /ping は認証不要で、ライブネスプローブに適しています。
• /auth/login は Cognito のメールアドレス＋パスワードからトークンへのショートカットを提供します（詳細は OIDC.md を参照）。
• 複数レプリカでデプロイする場合は --stateless-http が必要です。これを指定しないと、MCP のセッション状態はプロセスのメモリ内に保持され、ラウンドロビン負荷分散によってセッションが破損します。

TLS 証明書用 AWS Secrets Manager

データベースの TLS ルート証明書が AWS Secrets Manager に保存されている場合、サーバーは証明書を自動的に取得して使用できます。プレーンテキストの PEM に対応しており、JSON キー付きのバンドルも使用できます（選択するキーを YB_AWS_SSL_ROOT_CERT_KEY に設定してください）。

yugabytedb-mcp \
  --yugabytedb-url "host=… port=5433 dbname=… user=… password=… sslmode=verify-full" \
  --yb-aws-ssl-root-cert-secret-arn arn:aws:secretsmanager:us-east-1:…:secret:my-cert \
  --yb-aws-ssl-root-cert-secret-region us-east-1

Docker

docker build -t mcp/yugabytedb .
docker run -p 8000:8000 -e YUGABYTEDB_URL="…" mcp/yugabytedb yugabytedb-mcp --transport http

セキュリティ

• すべての SQL はパラメーター化クエリを通じて実行されます。ユーザー入力がステートメント文字列に直接埋め込まれることはありません。
• 書き込みツールはデフォルトで無効です。有効にするには、--enable-write-query を明示的に指定する必要があります。
• 書き込みツールのガードレールリスト（上記）は、リスクが最も高いステートメント種別をブロックします。
• destructiveHint: true により、Claude Desktop は書き込み操作の呼び出しごとに確認を表示します。
• OIDC 認証が有効な場合、ユーザーごとの SET ROLE によって、呼び出し元ごとにデータベースレベルの権限境界が適用されます。ロール名は psycopg.sql.Identifier を使用して安全に引用符で囲まれます。
• HTTP トランスポートでは、MCP_AUTH_PROVIDER が設定されている場合、有効な Bearer トークンが必要です。
• HTTP トランスポートでは、Origin ヘッダーが MCP_ALLOWED_ORIGINS（デフォルトは MCP_BASE_URL）と照合されます。
• HTTPS の設定は運用担当者の責任です。サーバーの前段にあるリバースプロキシ（nginx、ALB など）で TLS を終端してください。
• 最小権限のデータベースロールで実行してください（run_read_only_query のみを使用するデプロイでは読み取り専用ロール、それ以外では対象スキーマに限定したロールを使用し、スーパーユーザーは使わないでください）。

セキュリティ上の問題は [email protected] に非公開で報告してください。脆弱性について、公開の GitHub イシューを作成しないでください。

プライバシーポリシー

Yugabyte のプライバシーポリシーが適用されます：https://www.yugabyte.com/privacy-policy/

この MCP サーバーはテレメトリーを送信しません。すべてのデータベースアクセスは、指定した接続文字列を介して Claude（MCP クライアント）と YugabyteDB インスタンス間で行われます。サーバーはローカルの stderr にログを出力します（YB_LOG_LEVEL で制御）。リモートログ集約機能は組み込まれていません。

開発

git clone [email protected]:yugabyte/yugabytedb-mcp-server.git
cd yugabytedb-mcp-server
uv sync
uv run yugabytedb-mcp --help

注：src/server.py を直接実行することはできなくなりました。PyPI 配布向けにパッケージのレイアウトが再編成され（エントリーポイント＋名前空間）、モジュールは src/yugabytedb_mcp_server/ 以下に配置されています。必ず yugabytedb-mcp コンソールスクリプト経由で起動してください（uv sync／pip install によって登録されます）。モジュールファイルを python で実行すると、パッケージのインポート機構が使われず、相対インポートが失敗します。

同等のコマンド：

uv run yugabytedb-mcp                 # uses the console script
uv run python -m yugabytedb_mcp_server # uses the __main__.py shim

Claude Desktop でコネクターをローカルテストする

本番環境のインストール体験をどの程度再現したいかに応じて、2 つの方法があります。

最速 — MCPB をビルドせず、Claude Desktop にローカルのエントリーポイントを指定する。uv sync の後、yugabytedb-mcp スクリプトが（有効な仮想環境経由で）$PATH 上に配置されます。これを claude_desktop_config.json に追加してください。

{
  "mcpServers": {
    "yugabytedb-dev": {
      "command": "/absolute/path/to/repo/.venv/bin/yugabytedb-mcp",
      "env": {
        "YUGABYTEDB_URL": "host=localhost port=5433 dbname=yugabyte user=yugabyte password=yugabyte",
        "YB_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Claude Desktop を再起動してください。デバッグ出力を確認するには、~/Library/Logs/Claude/mcp-server-yugabytedb-dev.log（macOS）を使用します。これは MCPB のバンドル作成を完全に省略でき、ツールコードの反復開発に適した方法です。

本番環境に近い方法 — .mcpb をビルドして Claude Desktop にドラッグする。MCPB CLI が必要です。

npm install -g @modelcontextprotocol/mcpb-cli   # one-time
mcpb validate manifest.json                      # static check
mcpb pack .                                      # produces yugabytedb-mcp-server-<version>.mcpb

生成された .mcpb を Claude Desktop にドラッグしてください。あとはコネクターのインストーラー UI が処理し、manifest.json で定義された user_config の値を入力するよう求められます。.mcpb を使う方法は、レビュー担当者が実際に試す手順に最も近いものです。注：マニフェストの mcp_config は uvx yugabytedb-mcp-server を実行し、初回起動時に PyPI からパッケージを取得します。バンドルを共有する前に、.mcpb が参照するバージョンが公開済みであることを確認してください。

テスト

# unit tests (no DB, no network)
uv run pytest tests/test_guardrails.py tests/test_auth.py tests/test_identity_mapping.py

# integration tests (require a reachable Postgres-compatible DB)
YUGABYTEDB_URL="host=… port=… …" uv run pytest tests/

カバレッジ表と手動での Cognito スモークテスト手順については、tests/README.md を参照してください。

トラブルシューティング

• Claude Desktop で spawn yugabytedb-mcp ENOENT が表示される → インストールディレクトリが Claude Desktop から認識できる PATH 上にあることを確認してください。pipx ensurepath を実行するか、エントリーポイントを /usr/local/bin にシンボリックリンクしてください。
• MCP クライアントにツール一覧が表示されない → クライアントを再起動してください。ライフスパン中の接続エラーについては、YB_LOG_LEVEL=DEBUG の出力を確認してください。
• 複数レプリカ構成の HTTP+OAuth モードで「Invalid or expired transaction」／「Client Not Registered」と表示される → セルフホスト型リモートのセクションを参照してください。複数レプリカでは --stateless-http が必須です。

ライセンス

Apache License 2.0。