MCPg : Production Grade Postgresql Mcp Server

MCPg

PostgreSQL 向けの、本番環境対応のModel Context Protocolサーバーです。 AI エージェントが Postgres データベースを安全に調査、クエリ、操作、チューニングできます。カタログのイントロスペクション、クエリインテリジェンス、自然言語からの SQL 生成、構造差分、ハイブリッド検索、グラフクエリ、データ移動、ライブ運用など、279 個のツールを備えています。

ライブでお試しください： MCP クライアント、またはMCP Inspectorから、ホストされている読み取り専用のデモエンドポイント https://devopam-mcpg-demo.hf.space/mcp に接続してください。使い捨てのデモデータに対して読み取りツールを提供します。実際に使用する場合は、MCPg をご自身のデータベースのそばで実行してください（クイックスタートを参照）。

📍 掲載先

• 公式 MCP Registry
• mcp.so
• mcpservers.org
• Smithery
• Glama
• MCP ServerList

---

項目	MCPg
安全性	デフォルトで読み取り専用＋AST 検証
トランスポート	stdio＋HTTP/SSE
インストール	pip install mcpg
Postgres のバージョン	14–19
主な差別化要素	本番環境の可観測性＋マルチテナンシー

MCPg を選ぶ理由

• デフォルトで安全です。 読み取り専用アクセスモードを備えています。ユーザーが指定したすべての SQL ステートメントは、実行前に検証済みの AST 許可リストを通して解析されます。PostgreSQL に SQL 識別子として渡される名前は、ハイフンなどの有効な文字を含むという理由だけで拒否せず、区切り識別子として引用符で囲んでエンコードされます（識別子ポリシーを参照）。DDL、シェル、LISTEN/NOTIFY などの機能は、明示的に有効化するまで無効です。すべてのツールは、同じ制御設定に基づく MCP ToolAnnotations（readOnlyHint、openWorldHint）を公開するため、クライアントは推測に頼らず、読み取りを自動承認し、書き込みを制御できます。
• 1 つのサーバーで幅広い機能を提供します。 アプリケーションデータへのアクセス（クエリ、検索、カーソル、NL→SQL）と DBA レベルの操作（ヘルスチェック、インデックスのチューニング、EXPLAIN 分析、ロック、バキューム、ダンプ、レプリカ、マイグレーション）を、1 つの MCP サーバーで利用できます。エージェントはタスクを切り替えるためにツールを切り替える必要がありません。
• すべて PostgreSQL ネイティブです。 ORM や抽象化によるオーバーヘッドはなく、psycopg3 を直接使用して、すべての pg_* システムビューを扱います。TimescaleDB、pgvector、PostGIS、Apache AGE、pg_stat_statements が利用可能な環境では統合し、利用できない場合も適切に機能を縮退します。
• デモ向けではなく、本番運用を想定しています。 コネクションプーリング、リクエストごとの SET ROLE によるマルチテナント対応、劣化したホストの検出を伴う読み取りレプリカへのルーティング、専用接続を使用するサーバーサイドカーソル、レート制限、正規表現による秘匿化を備えた監査証跡、起動時の PG TLS 強制、OIDC JWT ベアラー認証、セッションごとのステートメント／ロックタイムアウトを備えています。
• オブザーバビリティを標準搭載しています。 HTTP トランスポートの Prometheus /metrics エンドポイントで、mcpg_tool_calls_total{tool,status} と mcpg_tool_duration_seconds を公開します。すべてのツール呼び出しで、認証情報を秘匿化した引数を含む構造化監査イベントを記録します。
• テスト駆動で、複数バージョンに対応しています。 2,500 件以上の単体テストに加え、CI では実際の PostgreSQL コンテナを使った統合テストスイートを実行します。マトリックステストでは、プッシュのたびに PG 14、15、16、17、18 を対象とし、さらに PG 19（ベータ版） も実験的な非ブロッキング項目として含まれ、イシュー #120 で追跡されています。

---

インストール

PyPI からインストール（推奨）

pip install mcpg
# or, in an isolated venv exposed globally:
uv tool install mcpg

確認：

mcpg --version

Docker

GitHub Container Registry からビルド済みイメージを取得します（タグ付きリリースごとに公開されます。:latest は最新バージョンを追跡するか、:0.6.5 のようにバージョンを固定してください）：

docker pull ghcr.io/devopam/mcpg:latest
docker run --rm --name mcpg -p 8000:8000 \
    -e MCPG_DATABASE_URL=postgresql://user:pass@host:5432/db \
    -e MCPG_ACCESS_MODE=read-only \
    ghcr.io/devopam/mcpg:latest

Windows PowerShell では、末尾の \ をバッククォート ` に置き換えるか、コマンドを 1 行にまとめてください。インストールガイドには、Linux/macOS、PowerShell、コマンドプロンプト用のコピーしてすぐ使えるコマンドブロックがあります。

または、ソースから自分でビルドします：

docker build -t mcpg https://github.com/devopam/MCPg.git

マルチステージイメージです。ランタイムステージではビルドツールチェーンを除外し、nologin シェルを使って uid=10001 / gid=10001 で実行します。アプリケーションファイルの所有者は root で、ランタイムユーザーからは読み取り専用です。

ソースからインストール（開発者向け）

git clone https://github.com/devopam/MCPg && cd MCPg
uv sync

uv sync は、ランタイムと開発の依存関係をすべて含む venv を作成し、mcpg コンソールスクリプトを利用可能にします。

詳しくはインストールガイドを参照してください。

---

クイックスタート

ワンクリックでインストール： — Windsurf、JetBrains、Zed、Cline、Antigravity、Qwen Code、Perplexity、 ChatGPT、Copilot Studio、Continue、および HTTP クライアントの設定については、統合ガイドをご覧ください。

Claude Desktop にワンクリックでインストール（.mcpb）

最新リリースから mcpg-<version>.mcpb をダウンロードし、 ダブルクリックするか、Claude Desktop の「設定」→ 「拡張機能」にドラッグします。PostgreSQL の接続 URL（OS の キーチェーンに保存）とアクセスモード（デフォルトは 読み取り専用）の入力を求められます。これでインストールは完了です。バンドルは約 2 kB で、 ホストがご利用のプラットフォーム向けに PyPI から固定された mcpg リリースを解決します。

または手動で設定（stdio トランスポート）

以下を claude_desktop_config.json に追加します（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json； Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "mcpg": {
      "command": "uvx",
      "args": ["mcpg"],
      "env": {
        "MCPG_DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Claude Desktop を再起動します。これで MCPg のツールセットをモデルで利用できるようになります。 Claude には、次のように尋ねることができます。

「このデータベースにはどのようなスキーマがありますか？それぞれについて、 最も大きなテーブルを 3 つ要約してください。」

「このクエリの実行が遅いのはなぜですか？ SELECT * FROM orders WHERE customer_id = 42 ORDER BY created_at DESC」

まだ面白いデータがありませんか？デモデータセットを投入しましょう

MCPG_DATABASE_URL=postgresql://... mcpg --demo

1 つのコマンドで、小規模に厳選された e コマースのデータセット（注文 3,000 件、 商品レビュー 900 件、意図的に仕込まれた不備）を mcpg_demo スキーマに投入します。初回からインデックスアドバイザー、クエリプラン分析、 全文検索、PII 監査、グラフ投影が実データを対象に動作するよう設計されています。 実行例を含むガイド付きツアーは こちらをご覧ください。mcpg --demo-drop を使えば、 いつでも削除できます。

HTTP サーバーとして実行（IDE 統合、ウェブアプリなど向け）

MCPG_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb \
MCPG_TRANSPORT=streamable-http \
MCPG_HTTP_PORT=8000 \
mcpg

次に、MCP 対応のクライアントを http://localhost:8000/mcp（SSE トランスポートの場合は /sse）に接続します。HTTP トランスポートは認証がないと起動しません。 静的ベアラートークンを使用するには MCPG_HTTP_AUTH_TOKEN=... を、 OIDC 発行者に対する完全な JWT 検証を行うには MCPG_AUTH_MODE=oidc を設定します。 意図的に認証なしで実行する場合（推奨しません）は、 MCPG_HTTP_ALLOW_UNAUTHENTICATED=true を設定してください。

---

設定

MCPg は環境変数のみで設定します。設定ファイルやフラグはありません（CLI の --version、--demo、 --demo-drop は設定ではなく、一度だけ実行するコマンドです）。必須の変数は MCPG_DATABASE_URL のみで、それ以外はすべて安全なデフォルト値が設定されています。

よくあるシナリオ

シナリオ	設定
ローカルでの探索、読み取り専用	MCPG_DATABASE_URL
アプリデータへの読み書きアクセス	MCPG_ACCESS_MODE=restricted
DBA ツールキット（DDL、バキュームなど）	MCPG_ACCESS_MODE=unrestricted + MCPG_ALLOW_DDL=true
ベアラー認証を使用する HTTP トランスポート	MCPG_TRANSPORT=streamable-http + MCPG_HTTP_AUTH_TOKEN=…
マルチテナント SaaS	MCPG_DEFAULT_ROLE=tenant_a + MCPG_ALLOWED_ROLES=tenant_a,tenant_b,…
読み取りレプリカへの分散	MCPG_REPLICA_URLS=postgresql://…?sslmode=require,postgresql://…?sslmode=require
NL→SQL — 単一プロバイダー	ベンダーキーをいずれか1つ設定します（ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、XAI_API_KEY、GROQ_API_KEY、HF_TOKEN、… — 組み込みプロバイダーは22種類）。MCPg がデフォルトを自動選択します。
NL→SQL — 複数プロバイダー、呼び出し側が選択	有効にするベンダーキーをすべて設定します。translate_nl_to_sql の各呼び出しで provider="…"（設定済みの組み込みまたはカスタムプロバイダー）を指定できます。

完全なリファレンス

コア

変数	デフォルト	説明
MCPG_DATABASE_URL	必須	プライマリ PostgreSQL DSN。URI 形式（postgresql://…）とキーワード形式（host=… user=…）をサポートします。リモートホストでは sslmode=require（またはそれ以上）が必要です。
MCPG_ACCESS_MODE	read-only	read-only | restricted（書き込みツールを許可） | unrestricted（ゲート変数と組み合わせると DBA ツールも有効になります）。
MCPG_TRANSPORT	stdio	stdio（デフォルト、Claude Desktop 用） | streamable-http | sse。
MCPG_LOG_LEVEL	INFO	DEBUG | INFO | WARNING | ERROR | CRITICAL。
MCPG_HTTP_HOST	127.0.0.1	HTTP トランスポートのバインドアドレスです。コンテナー内では 0.0.0.0 に設定してください。
MCPG_HTTP_PORT	8000	HTTP トランスポートの待ち受けポート（1～65535）です。

機能ゲート（影響範囲の大きいツールをオプトインで有効化）

変数	デフォルト	説明
MCPG_ALLOW_DDL	false	DDL ツール（run_ddl、create_graph、drop_graph、ハイパーテーブルツール、マイグレーションツール）を公開します。MCPG_ACCESS_MODE=unrestricted が必要です。
MCPG_ALLOW_SHELL	false	サブプロセスを使用するツール（dump_database、restore_database、run_pg_binary）を公開します。必要な PG クライアントバイナリが PATH 上にある必要があります。
MCPG_ALLOW_TIMESCALEDB_ADMIN	false	unrestricted モードと MCPG_ALLOW_DDL を有効にすると、破壊的または負荷の高い TimescaleDB ツール（drop_chunks、compress_chunk、decompress_chunk、reorder_chunk、merge_chunks、refresh_continuous_aggregate、run_job、alter_job、delete_job）を公開します。各ツールでは dry_run の後に confirm=true と confirmation_token が必要です。docs/timescaledb.md を参照してください。
MCPG_ALLOW_ALTER_SYSTEM	false	alter_system、alter_system_reset_all、reload_config を公開します（unrestricted モードのみ。2段階の confirm=true フローを使用します。docs/alter-system.md を参照）。MCPG_ALTER_SYSTEM_ALLOWLIST / MCPG_ALTER_SYSTEM_DENYLIST（GUC 名をカンマ区切りで指定）で、組み込みの拒否リストを絞り込んだり拡張したりできます。
MCPG_ALLOW_LISTEN	false	LISTEN/NOTIFY ツール（subscribe_channel、poll_notifications、unsubscribe_channel、list_notification_subscriptions）を公開します。

認証（HTTP トランスポートのみ）

変数	デフォルト	説明
MCPG_AUTH_MODE	static	static（ベアラーを MCPG_HTTP_AUTH_TOKEN と照合） | oidc（完全な JWT 検証）。
MCPG_HTTP_AUTH_TOKEN	—	MCPG_AUTH_MODE=static の場合に必須のベアラートークン。定時間比較を行います。これ、MCPG_AUTH_MODE=oidc、または MCPG_HTTP_ALLOW_UNAUTHENTICATED=true のいずれも設定されていない場合、HTTP トランスポートは起動を拒否します（ConfigError）。
MCPG_HTTP_ALLOW_UNAUTHENTICATED	false	HTTP トランスポートのフェイルクローズ認証チェックを明示的に無効にします。設定すると起動のたびに警告ログが出力されます。推奨されません。
MCPG_OIDC_ISSUER	—	OIDC 発行者 URL（MCPG_AUTH_MODE=oidc の場合に必須）。
MCPG_OIDC_AUDIENCE	—	想定される aud クレーム（MCPG_AUTH_MODE=oidc の場合に必須）。
MCPG_OIDC_JWKS_URL	検出された値	JWKS エンドポイントの上書き値（未設定の場合は、発行者の .well-known から自動検出されます）。
MCPG_OIDC_ROLE_CLAIM	—	値がリクエストごとの PG ロール（SET LOCAL ROLE）となる JWT クレーム。テナンシードライバーと組み合わせて使えます。

HTTP の強化（HTTP トランスポートのみ）

変数	デフォルト	説明
MCPG_HTTP_MAX_BODY_BYTES	1048576	（1 MiB）これを超えるリクエストボディには 413 が返されます。ストリーミングされたバイト数をカウントするため、Content-Length が欠落していても、または偽装されていても、この制限を回避できません。
MCPG_HTTP_ALLOWED_ORIGINS	—	カンマ区切りの CORS 許可リスト。未設定の場合、CORS ミドルウェアは使用されません（クロスオリジンヘッダーは出力されません）。
MCPG_HTTP_HSTS_MAX_AGE	63072000	Strict-Transport-Security の max-age（2 年。OWASP の現行推奨値）。0 にすると HSTS ヘッダーが無効になります。アプリがすでに設定している場合を除き、セキュリティヘッダー（CSP、X-Frame-Options、X-Content-Type-Options、Referrer-Policy）は常に追加されます。
MCPG_HTTP_REQUEST_TIMEOUT_SECONDS	0	リクエストごとの実時間上限（期限切れ時に 504）。0 は無効です。長時間接続の SSE / streamable-http ストリームに依存している場合は無効のままにしてください。厳格な上限を設けると、これらの接続も切断されます。
MCPG_HTTP_TRUSTED_HOSTS	—	許可する Host ヘッダー値のカンマ区切りリスト（*.example.com のようなワイルドカードに対応）。未設定の場合、Host ヘッダーの検証は行われません（現在の動作）。設定すると、一致しない Host のリクエストには Starlette の TrustedHostMiddleware により 400 が返されます。

マルチテナンシー（SET ROLE）

変数	デフォルト	説明
MCPG_DEFAULT_ROLE	—	すべてのクエリに適用される静的な PG ロール。識別子の検証が行われます。
MCPG_ALLOWED_ROLES	—	カンマ区切りの許可リスト。設定されている場合、X-MCPG-Role ヘッダー / OIDC ロールクレームの値はこのリストに含まれている必要があります。

リードレプリカ

変数	デフォルト	説明
MCPG_REPLICA_URLS	—	レプリカ DSN のカンマ区切りリスト。force_readonly クエリは正常なレプリカ間でラウンドロビンされます。障害時はプライマリにフォールバックし、劣化したレプリカの再試行期間は 30 秒です。

複数のデータベース（読み取り専用のセカンダリ）

変数	デフォルト	説明
MCPG_SECONDARY_DATABASE_URLS	—	この 1 つのサーバーが利用できる、追加の読み取り専用データベースを指定する name=dsn エントリのカンマ区切りまたは改行区切りリスト（例：analytics=postgresql://…?sslmode=require,reporting=postgresql://…?sslmode=require）。読み取り可能なツールでは、名前でセカンダリを選択する任意の database 引数を指定できます。省略するとプライマリが使われます。セカンダリは読み取り専用で、PostgreSQL によって強制されます（すべてのクエリは READ ONLY トランザクション内で実行されます）。そのため、書き込み / DDL / シェル / マイグレーションは常にプライマリを対象とします。名前は単純な識別子（[a-z0-9_]+）で、一意であり、primary（MCPG_DATABASE_URL 用に予約された ID）以外である必要があります。TLS のルールはプライマリ DSN と同じです。list_databases を呼び出すと、設定されている ID と到達可能性を確認できます。

プール／タイムアウト／TLS

変数	デフォルト	説明
MCPG_POOL_MIN_SIZE	1	プールの最小接続数です。
MCPG_POOL_MAX_SIZE	5	プールの最大接続数です。MCPG_POOL_MIN_SIZE 以上である必要があります。
MCPG_STATEMENT_TIMEOUT_MS	30000	接続取得時に設定される、セッションごとの statement_timeout です。長時間実行されるクエリは自動的に終了します。
MCPG_LOCK_TIMEOUT_MS	5000	セッションごとの lock_timeout です。ロック待ちが長時間続く場合は自動的に終了します。
MCPG_ENABLE_ANALYTICAL_QUERIES	true	run_analytical_query（分離されたプールで実行される長時間読み取り）を公開します。ツールを無効にするには false に設定します。
MCPG_ANALYTICAL_TIMEOUT_MS	120000	run_analytical_query の呼び出しごとのデフォルト実行時間（2 分）です。
MCPG_ANALYTICAL_MAX_TIMEOUT_MS	600000	run_analytical_query の最大実行時間です。呼び出しごとの timeout_ms はこの値が上限になります（10 分）。MCPG_ANALYTICAL_TIMEOUT_MS 以上である必要があります。
MCPG_ANALYTICAL_MAX_CONCURRENCY	2	分離された分析用プールのサイズです。run_analytical_query の同時呼び出し数の上限です。
MCPG_ALLOW_INSECURE_TLS	false	sslmode=require（またはそれ以上）を指定していないリモート DSN を拒否する起動時の TLS チェックを回避します。ループバックホストは常に対象外です。
MCPG_SHUTDOWN_DRAIN_SECONDS	30	SIGTERM を受信したとき、プールとカーソルを閉じる前に、実行中のツール呼び出しが完了するまで待機する最大時間です。

サブプロセスツール（MCPG_ALLOW_SHELL=true の場合のみ）

変数	デフォルト	説明
MCPG_SHELL_TIMEOUT_SEC	60	pg_dump／pg_restore／psql の実行における最大経過時間です。
MCPG_SHELL_MAX_OUTPUT_BYTES	67108864	（64 MiB）サブプロセス呼び出しごとにキャプチャする標準出力の上限です。
MCPG_SUBPROCESS_BIN_ALLOWLIST	—	解決された pg_dump／pg_restore／psql の配置先として許可する絶対パスのディレクトリをカンマ区切りで指定します。空の場合は PATH を信頼します。これらのバイナリを PATH 上の別の実行ファイルに差し替える手法を防ぎます。
MCPG_SUBPROCESS_CPU_SECONDS	—	子プロセスごとの RLIMIT_CPU（秒）です。POSIX のみ対応します。未設定の場合は継承します。
MCPG_SUBPROCESS_MEMORY_MB	—	子プロセスごとの RLIMIT_AS（MiB）です。POSIX のみ対応します。未設定の場合は継承します。

LISTEN/NOTIFY（MCPG_ALLOW_LISTEN=true の場合のみ）

変数	デフォルト	説明
MCPG_LISTEN_QUEUE_MAX	1000	チャネルごとのバッファーサイズです。あふれた場合は、最も古い通知が破棄されます。

監査

変数	デフォルト	説明
MCPG_AUDIT_PERSIST	false	true の場合、すべての run_write／run_ddl 呼び出しを mcpg_audit.events テーブルに永続化します（テーブルは冪等に自動作成されます）。
MCPG_AUDIT_REDACT_KEYS	—	シークレット名のパターンに追加する正規表現フラグメントをカンマ区切りで指定します（デフォルトで password、passwd、secret、token、api[_-]?key、bearer、authorization、database_url、dsn、conninfo はすでに対象です）。
MCPG_AUDIT_INTEGRITY	false	true の場合、永続化される各イベントに、前のイベントと連鎖する HMAC 署名を付与します。verify_audit_chain ツールはチェーンをたどり、最初の不整合を報告します。MCPG_AUDIT_HMAC_KEY が必要です。
MCPG_AUDIT_HMAC_KEY	—	監査 HMAC チェーンの秘密鍵です。MCPG_AUDIT_INTEGRITY=true の場合に必要です。repr／ログには決して表示されません。

シークレットバックエンド

デフォルトでは、すべてのシークレットを環境変数から直接読み込みます。 API キー／ベアラートークン／ HMAC キーをマウントされたファイルから読み込むには、 MCPG_SECRETS_BACKEND=file を設定します。ファイル内に値があればその値が優先され、ない場合は環境変数にフォールバックするため、一部の値だけを含むファイルも使用できます。

変数	デフォルト	説明
MCPG_SECRETS_BACKEND	env	env（すべてのシークレットを環境変数から読み込みます）| file（シークレットファイルを環境変数に重ねて読み込みます）。
MCPG_SECRETS_FILE_PATH	—	MCPG_SECRETS_BACKEND=file の場合に必須です。フラットな name → value マップへのパスです。JSON は常に使用でき、PyYAML がインストールされている場合は YAML（.yaml／.yml）も使用できます。ANTHROPIC_API_KEY／OPENAI_API_KEY／GEMINI_API_KEY／GOOGLE_API_KEY／MCPG_NL2SQL_API_KEY、MCPG_HTTP_AUTH_TOKEN、MCPG_AUDIT_HMAC_KEY が対象です。

レート制限

変数	デフォルト	説明
MCPG_RATE_LIMIT_ENABLED	true	ツールごとのトークンバケット方式のレート制限です。false に設定すると、変更前の無制限の動作に戻ります。
MCPG_RATE_LIMIT_MAX_REQUESTS	60	すべてのツールを対象とした、ウィンドウごとの全体上限です。
MCPG_RATE_LIMIT_WINDOW_SECONDS	60	全体クォータのウィンドウの長さです。
MCPG_RATE_LIMIT_HEAVY_MAX	5	高負荷ツール（run_write、run_ddl、dump_database など）の上限です。
MCPG_RATE_LIMIT_HEAVY_WINDOW	60	高負荷ツールのクォータのウィンドウの長さです。

キャッシュと機能フラグ

変数	デフォルト	説明
MCPG_CACHE_ENABLED	true	適応型キャッシュレイヤーを有効または無効にします。
MCPG_CACHE_TTL_SECONDS	300	デフォルトのキャッシュ有効期間（秒）です。
MCPG_CACHE_MAXSIZE	1024	メモリーキャッシュの LRU 容量の上限です。
MCPG_REDIS_URL	—	外部の複数ノードキャッシュ用の、任意の Redis バックエンド接続文字列です。
MCPG_ENABLE_HEAVY_DIAGNOSTICS	true	計算負荷の高い診断、図表、アドバイザーツールの有効・無効を切り替えます。
MCPG_ELICIT_CONFIRM_WRITES	false	true の場合、書き込み／DDL／シェル／リッスン／移行レベルの各ツール呼び出し（readOnlyHint アノテーションが true ではないツールすべて）では、実行前に対話型の確認（ctx.elicit()）を求め、承認を得る必要があります。ベストエフォートであり、強制の境界ではありません。リクエストの context を渡し、initialize 中に elicitation 機能を宣言するクライアントに対してのみ有効です。どちらかを省略したクライアントは、ゲートを通知なしに回避し、ツールは通常どおり実行されます。

自然言語 SQL

MCPg は起動時に、環境で設定されているすべてのプロバイダーを自動検出します。利用するベンダーのキーを必要な数だけ設定すると、それぞれが呼び出し可能になります。19 のプロバイダーが組み込みで提供されています。 そのうち 3 つはファーストパーティ（Anthropic、OpenAI、Gemini）で、残りの 16 はベンダーごとに事前設定されたエンドポイントを使う OpenAI 互換 API に対応しています。DeepSeek、Qwen、OpenRouter、Perplexity、xAI （Grok）、Groq、Mistral、Together、Fireworks、DeepInfra、Cerebras、Nebius、 Hugging Face、GitHub Models、SambaNova、Moonshot（Kimi） が含まれます。組み込みプロバイダーはどれもプラグアンドプレイで、ベンダーで一般的に使われる API キーの環境変数を設定すれば自動検出されます。また、その他の OpenAI 互換ベンダーやローカルモデルサーバー（Ollama、vLLM、LM Studio）も、設定だけでプラグインできます。設定には MCPG_NL2SQL_CUSTOM_PROVIDERS を使います。組み込みプロバイダーの一覧は nl2sql.py の宣言的なレジストリ 1 つで管理されているため、ベンダーの追加や、提供終了したデフォルトモデルの更新はデータを 1 行変更するだけです。

MCPG_NL2SQL_PROVIDER が設定されていない場合、MCPg はレジストリの順序に従ってデフォルトを自動選択します。既存のデプロイメントに影響しないよう、anthropic → openai → gemini が先頭に並びます。translate_nl_to_sql は呼び出しごとに振り分けるための省略可能な provider="…" 引数を受け付けます。get_server_info では、設定されているプロバイダーを確認できます。

変数	デフォルト	説明
<VENDOR>_API_KEY	—	ベンダーで一般的に使われるキーを設定すると、そのプロバイダーが有効になります。標準的なスラッグ：ANTHROPIC_API_KEY、OPENAI_API_KEY、DEEPSEEK_API_KEY、OPENROUTER_API_KEY、PERPLEXITY_API_KEY、XAI_API_KEY、GROQ_API_KEY、MISTRAL_API_KEY、TOGETHER_API_KEY、FIREWORKS_API_KEY、CEREBRAS_API_KEY、NEBIUS_API_KEY、SAMBANOVA_API_KEY、MOONSHOT_API_KEY。
(標準と異なるキー)	—	一部のベンダーでは <VENDOR>_API_KEY とは異なる形式を使います。Gemini → GEMINI_API_KEY または GOOGLE_API_KEY、Qwen → DASHSCOPE_API_KEY または QWEN_API_KEY、Hugging Face → HF_TOKEN、GitHub Models → GITHUB_TOKEN、DeepInfra → DEEPINFRA_TOKEN。
MCPG_NL2SQL_PROVIDER	自動選択	組み込みのスラッグ（上記一覧）またはカスタム名を指定します。ツールが provider= なしで呼び出された場合に使うデフォルトのプロバイダーを固定します。未設定で、いずれかのベンダーキーが設定されている場合、MCPg はレジストリの順序に従って自動選択します。
MCPG_NL2SQL_API_KEY	—	設定済みの MCPG_NL2SQL_PROVIDER に明示的に指定するキーです。そのプロバイダーについてのみ、ベンダーで一般的に使われる環境変数の値を上書きします。MCPG_NL2SQL_PROVIDER の設定が必要です。
MCPG_NL2SQL_MODEL	プロバイダーのデフォルト	デフォルトモデルを上書きします（例：claude-sonnet-4-6、gpt-4o-mini、grok-3-mini）。デフォルトのプロバイダーにのみ適用されます。
MCPG_NL2SQL_BASE_URL	—	デフォルトのプロバイダーのエンドポイントを上書きします（プライベートゲートウェイ／リージョン別エンドポイント）。
MCPG_NL2SQL_CUSTOM_PROVIDERS	—	コードを変更せずに、独自のプロバイダーを追加できます。 組み込みプロバイダーに加える追加の OpenAI 互換プロバイダー（ローカルの Ollama／vLLM／LM Studio、またはニッチなベンダー）を宣言する、カンマまたは改行区切りの name=base_url|model エントリーです。慣例に従い <NAME>_API_KEY からキーを取得します。形式が異なる場合は |KEY_ENV_VAR を追加します。ループバックエンドポイントではキーなしでも使用できます。それぞれの名前を provider= で呼び出せるようになります。
MCPG_NL2SQL_MAX_TOKENS	2048	生成トークン数の上限です（ハードリミット：16384）。

---

使用例

MCP ツールは、自然言語の指示に応じてエージェント（Claude、Cursor、Continue、…）が呼び出します。いくつかの実行例を紹介します。

スキーマを確認する

あなた： public スキーマにはどのテーブルがあり、行数が最も多いのはどれですか？

エージェント（list_tables + summarize_table × N を使用）： 6 つのテーブルがあります：customers（120 万行）、orders（470 万行）、line_items （1,830 万行）、products（340 行）、addresses（140 万行）、audit_log （4,580 万行 — 最も大きく、保持期間を設けずに蓄積されています）。

遅いクエリを診断する

あなた： なぜ SELECT * FROM orders o JOIN line_items l ON o.id = l.order_id WHERE o.created_at > now() - interval '7 days' は 8 秒もかかるのですか？

エージェント（why_is_this_slow と recommend_indexes を使用）： EXPLAIN ANALYZE では、orders（470 万行）に対する シーケンシャルスキャンが示されています。created_at で 絞り込んでいますが、orders.created_at にインデックスがありません。 推奨： CREATE INDEX CONCURRENTLY orders_created_at_idx ON orders (created_at DESC); 期待される改善：およそ 95％の削減（フルテーブルではなく、 インデックススキャンで約 3 万 3 千行を参照します）。適用する前に validate_migration を実行し、予期しないロックがないことを確認してください。

平易な英語を SQL に変換する

あなた： 今月は注文したものの、過去 3 か月間は一度も 注文していない顧客を探してください。メールアドレスと現在の 生涯支出額を表示してください。

エージェント（translate_nl_to_sql を使用）：

SELECT c.email, SUM(l.price * l.quantity) AS lifetime_spend
FROM customers c
JOIN orders o ON o.customer_id = c.id
JOIN line_items l ON l.order_id = o.id
WHERE EXISTS (
  SELECT 1 FROM orders o2 WHERE o2.customer_id = c.id
    AND o2.created_at >= date_trunc('month', now()))
  AND NOT EXISTS (
  SELECT 1 FROM orders o3 WHERE o3.customer_id = c.id
    AND o3.created_at >= date_trunc('month', now()) - interval '3 months'
    AND o3.created_at <  date_trunc('month', now()))
GROUP BY c.email;

スキーマを図で確認する

あなた： public スキーマの ER 図を作成してください。

エージェント（generate_schema_diagram を使用）： GitHub ／ Notion ／ Obsidian にそのまま貼り付けられる Mermaid 図を返します。

データベースを監査する

あなた： 現在、このデータベースの健全性はどの程度ですか？

エージェント（audit_database を使用）： 評価付きのレポートを返します： メモリと I/O のスコア 92（GOOD）、トランザクションと接続のスコア 78（WARNING： ロールバック率 0.4％。アプリのログを確認してください）、同時実行とロックのスコア 60 （CRITICAL：14 個のバックエンドが待機中）、クリーン度と肥大化のスコア 88（GOOD）、遅い クエリのスコア 70（WARNING：上位のクエリテンプレートが 5000 回実行され、平均 90 ms — optimize_query を参照してください）。

ガード付きの書き込みを実行する

あなた： 5 年以上前の注文をすべて論理削除してください。

エージェント（MCPG_AUDIT_PERSIST=true を指定して run_write を使用）： ステートメントを セーフ SQL カーネルで検証し、トランザクション内で実行して、 影響を受けた行数を返します。呼び出し内容（SQL と引数 — シークレットは正規表現でマスキング済み — およびステータス）を mcpg_audit.events に保存し、後から確認できるようにします。

マルチテナントルーティング、RLS テスト、NL→SQL、 ハイブリッドなベクトル検索 + FTS、Apache AGE Cypher、TimescaleDB、ORM スキーマの エクスポート、サーバーサイドカーソルなど、さらに多くのレシピについては docs/cookbook.md をご覧ください。

---

内容一覧

カテゴリ別の簡潔な一覧です。最新の完全なツールリファレンスについては docs/tools.mdをご覧ください。ガイド付きのウォークスルーについては docs/tour.mdをご覧ください。

• カタログの詳細確認 — スキーマ、テーブル、列、インデックス、 制約、ビュー、関数、トリガー、シーケンス、パーティション、 ポリシー、ロール、権限付与、列挙型、ドメイン、複合型、FDW、 パブリケーション、サブスクリプション、拡張機能、生成列。
• クエリ分析 — run_select、run_select_parallel、 explain_query、analyze_query_plan、why_is_this_slow、 recommend_indexes、analyze_workload、check_database_health、 detect_n_plus_one、audit_database。
• 検索 — fuzzy_search（トライグラム）、full_text_search、 vector_search、hybrid_search（pgvector + FTS と RRF）、 geo_search（PostGIS k-NN）。
• 自然言語 → SQL — translate_nl_to_sql（組み込みプロバイダーは22種類 — Anthropic、OpenAI、Gemini、xAI、Groq、Mistral、Hugging Face、… — に加え、任意のOpenAI互換エンドポイントに対応。出力は 手書きのクエリと同じセーフSQLカーネルを通過します）。
• 可視化 — generate_schema_diagram（ER）、 generate_fk_cascade_graph（ON DELETE CASCADEの影響範囲）、 generate_graph_diagram（Apache AGEプロパティグラフ）。
• 構造差分とマイグレーション — compare_schemas、 validate_migration、段階的な prepare_migration / complete_migration / cancel_migration ワークフロー。
• Apache AGEグラフ + Cypher — list_graphs、describe_graph、 run_cypher、create_graph、drop_graph、generate_graph_diagram。
• 複合ツール + アドバイザーツール — summarize_table、 find_unused_objects、find_sensitive_columns（PIIのヒューリスティック判定）、 lint_naming_conventions、test_rls_for_role、list_locks、 find_blocking_chains、read_pg_stat_io（PG16+）、 generate_test_data。
• ライブ運用とメンテナンス — list_active_queries、 verify_connection_encryption（ライブ接続のTLSステータス）、 run_maintenance（VACUUM/ANALYZE）、prune_audit_events （監査ログの保持期間管理）、cancel_query、terminate_backend、 run_write、run_ddl、enable_extension。
• データ移行 — export_query / export_table（CSV/JSON）、 dump_database / restore_database、import_csv / import_json （COPY FROM STDIN）、copy_table_between_databases。
• サーバーサイドカーソル — open_cursor、fetch_cursor、 close_cursor、list_cursorsにより、数百万行を対象としたページ単位の読み取りに対応します。
• TimescaleDB — ハイパーテーブル / チャンク / ジョブ / 継続的集約の 詳細確認と統計、ポリシーとディメンションの管理、制限付きの チャンク / ジョブ管理（drop_chunks、compress_chunk、 refresh_continuous_aggregate、run_job、…）。詳しくは docs/timescaledb.mdをご覧ください。
• ORMスキーマエクスポーター — Prisma、Drizzle、SQLAlchemy、sqlc、 Diesel、jOOQ、Ent、Ecto。
• イベントストリーム — subscribe_channel、poll_notifications、 unsubscribe_channel、list_notification_subscriptionsにより、 PostgreSQLのLISTEN/NOTIFYをMCPのポーリングモデルに橋渡しします。
• オブザーバビリティ — Prometheusの/metricsエンドポイント + stdio用のget_metrics_expositionツール。正規表現ベースで認証情報を秘匿する 構造化監査ログ。

---

ドキュメント

• docs/installation.md — インストールと設定
• docs/tour.md — ツールを順に紹介するガイド
• docs/cookbook.md — エージェント向けの実践的なレシピ
• docs/tools.md — ツールの完全なリファレンス
• docs/architecture.md — 各要素がどのように連携するか
• docs/scaling.md — プールのサイズ設定、レプリカ、パフォーマンス
• docs/security-hardening.md — セキュリティ機能のロードマップ
• docs/release-process.md — リリースを PyPI に公開する方法
• docs/adr/ — アーキテクチャ決定記録
• https://devopam.github.io/MCPg/ で閲覧できます

---

セキュリティ

• 脆弱性の報告については、SECURITY.md をご覧ください。調整済みの情報開示期間は 90 日間です。報告先は [email protected] です。
• 多層防御：機能ゲート、SafeSQL カーネル、識別子の許可リスト、監査ログの秘匿化、起動時の PG TLS 強制、レート制限、OIDC JWT 検証、セッションごとのタイムアウト。
• 提供済み（✅）および対応待ち（⬜）の強化項目をまとめた継続的なロードマップについては、docs/security-hardening.md をご覧ください。

プライバシーポリシー

MCPg はセルフホスト可能です。データベースの内容がインフラストラクチャの外部に送信されることはなく、テレメトリや外部への自動通信も一切ありません。明記されている例外は、オプトインの translate_nl_to_sql ツールです。このツールは、質問とスキーマのコンテキスト（行データではなく名前）を、お客様が設定した LLM プロバイダーに送信します。データの収集、使用、保存、第三者との共有、保持、連絡先を含むポリシー全文は、PRIVACY.md に記載されています。

---

リリースノートと変更履歴

全バージョンの履歴については CHANGELOG.md、リリースの作成方法については docs/release-process.md、ダウンロード可能な成果物については GitHub Releases ページをご覧ください。

---

コントリビューション

プルリクエストを歓迎します。開発ループのセットアップ、テストの規約、プルリクエストごとのレビュー用チェックリストについては、CONTRIBUTING.md をご覧ください。参加にあたっては、行動規範（Contributor Covenant 2.1）が適用されます。

---

ライセンス

MIT — LICENSE をご覧ください。SQL セーフティカーネル（src/mcpg/sql/）は、MIT ライセンスの crystaldba/postgres-mcp を参考に、独自に再実装したものです。由来については NOTICE をご覧ください。

ラップしている拡張機能 — 確認しておくべきライセンス

MCPg のソースコードは MIT ライセンスですが、ラップしている PostgreSQL 拡張機能にはそれぞれ独自のライセンスがあります。ラッパーは拡張機能から独立しており（SQL レベルの呼び出しのみで、MCPg の Python プロセスへの静的リンクや動的リンクはありません）、MCPg プロジェクト自体はどの拡張機能の派生著作物にもあたりません。MCPg と特定の拡張機能を使って構築したサービスをデプロイする運用者は、その拡張機能のライセンスで定められた義務を負います。拡張機能を直接インストールする場合と同じです。以下の一覧では、各ラップ対象の拡張機能のライセンスを示しているため、情報に基づいて選択できます。

拡張機能	ライセンス	運用者向けの注意事項
pgvector	PostgreSQL License（BSD スタイル）	寛容なライセンスで、特別な義務はありません。
pg_partman	PostgreSQL License	寛容なライセンスです。
pg_cron	PostgreSQL License	寛容なライセンスです。
pg_turboquant	MIT	寛容なライセンスです。
pg_buffercache / pg_walinspect / pgstattuple	PostgreSQL contrib	寛容なライセンスです。
TimescaleDB	Apache 2.0（コミュニティ版）＋一部機能に Timescale License（TSL、ソース公開型）	複合ライセンスです。TSL の適用対象となる機能については Timescale のドキュメントを参照してください。
Apache AGE	Apache 2.0	寛容なライセンスです。
pg_search（ParadeDB）	AGPL-3.0	ユーザーが pg_search を利用できるネットワークサービスを運営する場合、AGPL のネットワーク条項が適用されます。通常、ユーザーに pg_search（および変更を加えた場合はその変更分）のソースコードを提供する義務が生じます。MCPg のラッパーによって、この義務が MCPg 自体にまで及ぶことはありません。拡張機能をデプロイし、ネットワーク経由で「提供」する際に義務を負います。サービスの再配布モデルが AGPL のネットワーク条項と両立しない場合は、別の BM25 実装を選んでください（BM25 plan に代替案が記載されています）。

この一覧はあくまで出発点です。特定のデプロイに適用される正式な判断については、拡張機能の上流リポジトリにある LICENSE ファイルを確認し、（法的に重要な場合は）ご自身の弁護士にご相談ください。

免責事項。 MCPg を本番環境で使える品質にするため、最善の努力を払っていますが、現在も活発に開発されているプロジェクトであり、問題が含まれている可能性があります。補償に関する詳細はライセンス条項をご覧ください。