MCP PostgreSQL Server

MCP PostgreSQL Server

ローカル、Docker、RDS、Neon、Supabase のデータベースに対応した、PostgreSQL 用の Model Context Protocol（MCP）サーバーです。

このサーバーは小規模で監査しやすく、実行時依存関係は MCP SDK、pg、pg-connection-string、zod の4つです（SSH トンネリングにのみ使用するオプションの依存関係として ssh2 もあります）。

Node.js 20 以降が必要です。

クイックスタート

サーバーの設定には、単一の DATABASE_URL を使用する方法を推奨します。

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-postgres-server"],
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/mydb",
        "PG_ALLOW_WRITE": "false"
      }
    }
  }
}

PG_ALLOW_WRITE を "false" に設定すると、サーバーはデータベースへの読み取り専用アクセスとなります。これがデフォルトです。モデルによる書き込みが必要な場合にのみ、"true" に設定してください。

同じ JSON は、VS Code、Cursor、Claude Code、Codex、Windsurf など、stdio に対応するあらゆる MCP クライアントで使用できます。

また、個別の PG_* 変数を設定することもできます。これらは DATABASE_URL が設定されていない場合に使用されます。

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-postgres-server"],
      "env": {
        "PG_HOST": "your_host",
        "PG_PORT": "5432",
        "PG_USER": "your_user",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "your_database",
        "PG_ALLOW_WRITE": "false"
      }
    }
  }
}

手動インストール

npm install mcp-postgres-server

または、次のコマンドで直接実行します。

npx mcp-postgres-server

データベースへの接続

ローカルの Postgres：

DATABASE_URL=postgres://mcp_readonly:secret@localhost:5432/mydb

Docker 内の Postgres： データベースが公開ポートを持つコンテナー内で動作している場合は、通常どおり localhost:<published-port> に接続します。MCP サーバー自体がコンテナー内で動作し、データベースがホストマシン上で動作している場合は、localhost の代わりに host.docker.internal を使用してください。

DATABASE_URL=postgres://mcp_readonly:[email protected]:5432/mydb

Amazon RDS：

DATABASE_URL=postgres://mcp_readonly:[email protected]:5432/mydb?sslmode=require

Neon：

DATABASE_URL=postgres://mcp_readonly:[email protected]/mydb?sslmode=require

Supabase：

DATABASE_URL=postgres://postgres.xxxxxxxx:[email protected]:5432/postgres?sslmode=require

ツール

ツールの利用可否は設定によって異なります。

ツール	利用可否
query、list_schemas、list_tables、describe_table	常に利用可能
execute	常に利用可能（PG_ALLOW_WRITE=true でない場合、書き込みを拒否します）
connect_db	PG_ENABLE_RUNTIME_CONNECT=true の場合のみ利用可能

1. query

読み取り専用の SQL 文を実行します。SELECT、WITH ... SELECT、EXPLAIN、SHOW を受け付けます。呼び出しごとに1つの文を指定してください。拡張クエリプロトコルでは複数の文を含む入力は拒否されます。読み取り専用モード（デフォルト）では、BEGIN READ ONLY、クエリ、ROLLBACK の順に実行されます。これは3つのコマンドで、パイプライン処理によりネットワーク往復はおよそ2回です。そのため、データベース自体が書き込みを拒否します。PG_ALLOW_WRITE=true の場合、ラッパーを介さずに文が直接送信されるため、query で実行した書き込みは実際に実行されます。書き込みには execute を使用してください。PostgreSQL 形式の $1, $2 プリペアドステートメントパラメーターに対応しています。値はドライバーによってバインドされ、SQL テキストに直接挿入されることはありません。

use_mcp_tool({
  server_name: "postgres",
  tool_name: "query",
  arguments: {
    sql: "SELECT * FROM users WHERE id = $1",
    params: [1]
  }
});

コンパクトな JSON を返します：{"rows": [...], "rowCount": n, "returnedRows": n, "truncated": false}。 シリアライズされた行が PG_MAX_RESULT_BYTES を超える場合、収まる行のみが返されます（returnedRows < rowCount）。truncated は true となり、LIMIT／WHERE を追加するか、選択する列を減らすようヒントが表示されます。

2. list_schemas

接続先データベースのすべてのスキーマを一覧表示します。

use_mcp_tool({
  server_name: "postgres",
  tool_name: "list_schemas",
  arguments: {}
});

3. list_tables

接続先データベースのテーブルを一覧表示します。オプションのスキーマパラメーターを指定できます（デフォルトは 'public'）。

// List tables in the 'public' schema (default)
use_mcp_tool({
  server_name: "postgres",
  tool_name: "list_tables",
  arguments: {}
});

// List tables in a specific schema
use_mcp_tool({
  server_name: "postgres",
  tool_name: "list_tables",
  arguments: {
    schema: "my_schema"
  }
});

4. describe_table

特定のテーブルの構造（列、型、NULL 許容性、デフォルト値、主キー）を取得します。オプションのスキーマパラメーターを指定できます（デフォルトは 'public'）。

use_mcp_tool({
  server_name: "postgres",
  tool_name: "describe_table",
  arguments: {
    table: "users",
    schema: "my_schema"  // optional
  }
});

5. execute - PG_ALLOW_WRITE=true が必要

INSERT、UPDATE、DELETE、または DDL 文を実行します。常に登録されますが、読み取り専用モード（デフォルト）では PG_ALLOW_WRITE を示すエラーを返して拒否され、変更は行われません。文がデータベースに送信されることもありません。PG_ALLOW_WRITE=true の場合は実行されます。query と同じ $1, $2 パラメーター処理に対応し、呼び出しごとに完全な文を1つ指定します。実行できる操作は、接続に使用するロールによって決まります。{"rowCount": n, "command": "INSERT"} を返します。

use_mcp_tool({
  server_name: "postgres",
  tool_name: "execute",
  arguments: {
    sql: "INSERT INTO users (name, email) VALUES ($1, $2)",
    params: ["John Doe", "[email protected]"]
  }
});

6. connect_db - PG_ENABLE_RUNTIME_CONNECT=true が必要です

指定した認証情報を使用して、実行時に別の PostgreSQL データベースへ接続します。デフォルトでは登録されません。認証情報がモデルから見える引数を経由しないよう、環境変数で設定することを推奨します。セッション制限（statement_timeout、idle_in_transaction_session_timeout）は再接続のたびに再適用されます。読み取り専用の読み取り処理では、独自の BEGIN READ ONLY トランザクションによって読み取り専用を強制します。

use_mcp_tool({
  server_name: "postgres",
  tool_name: "connect_db",
  arguments: {
    host: "localhost",
    port: 5432,
    user: "your_user",
    password: "your_password",
    database: "your_database"
  }
});

設定リファレンス

変数	デフォルト	説明
DATABASE_URL	-	完全な接続文字列（推奨）。URL 内の ?sslmode= をサポートします。
PG_HOST	-	データベースのホスト（DATABASE_URL が設定されていない場合の代替）
PG_PORT	5432	データベースのポート
PG_USER	-	データベースのユーザー
PG_PASSWORD	-	データベースのパスワード
PG_DATABASE	-	データベース名
PG_ALLOW_WRITE	false	true の場合、execute で書き込みが実行され、読み取りは直接送信されます。オフ（デフォルト）では読み取り専用となり、execute は書き込みを拒否し、各読み取りは READ ONLY トランザクション内で実行されます
PG_SSLMODE	-	disable | allow | prefer | require | verify-ca | verify-full。require／allow／prefer は証明書を検証せずに暗号化します。verify-ca／verify-full は検証します（PG_SSL_CA で CA を指定してください）。認識されない値を設定すると、起動時にエラーになります。制限： libpq とは異なり、allow／prefer は平文通信にフォールバックしません（node-postgres は機会的な SSL に対応していません）。そのため、TLS に対応していないサーバーでは disable が必要です。
PG_SSL_CA	-	CA 証明書ファイルへのパス。これだけを設定した場合は verify-full が適用されます
PG_ENABLE_RUNTIME_CONNECT	false	connect_db ツール（実行時の認証情報切り替え）を登録します
PG_MAX_RESULT_BYTES	32768	モデルに送信する query 結果のバイト数上限です。上限内に収まる間は行全体が保持されます。上限を超えると returnedRows < rowCount となり、truncated: true が返されます（最初の行すら収まらない場合は、ヒントとともに returnedRows が 0 になります）。約 32 KiB は約 8k トークンに相当します。厳格なクライアントでは値を下げ、クライアントがより大きな値を許容する場合は上げてください。
PG_STATEMENT_TIMEOUT	30000	すべてのセッションに適用される、ミリ秒単位のステートメントタイムアウト
PG_CONNECT_TIMEOUT	10000	1 回の接続試行に対するミリ秒単位のタイムアウト（低速な回線や SSH トンネルを使用する場合は、値を大きくしてください）

踏み台経由でのみアクセスできるデータベースへの接続については、SSH トンネリング を参照してください（PG_SSH_* 変数が追加されます）。

機能

• デフォルトでは読み取り専用です。書き込みは明示的に有効にする必要があります（PG_ALLOW_WRITE=true）
• 読み取り専用はクライアント側の SQL 解析ではなく、エンジンによって強制されます（BEGIN READ ONLY）
• データアクセスは小規模な型付きインターフェースの背後にあり、pg ドライバーがその外部に漏れることはありません
• SSL 対応の DATABASE_URL をサポートします（sslmode=disable|allow|prefer|require|verify-ca|verify-full、カスタム CA）
• プリペアドステートメントのパラメーターに対応しています。$1 形式のプレースホルダーをドライバーでバインドします
• 結果サイズにバイト数の上限を設け、モデルのコンテキストに過剰なデータを流し込む代わりに、truncated フラグで切り詰めを明示します
• セッション単位のステートメントタイムアウトに加え、クライアント側の期限を設定します。トランザクションプーラーではセッション設定が保持されない場合があります
• SQLSTATE に基づくヒント付きの読みやすいツール結果としてエラーを返すため、モデルは自ら修正できます
• 接続が切断されてもクラッシュせず、必要に応じて遅延再接続します
• ホスト鍵の検証を必須とする任意の SSH トンネリング（PG_SSH_*）に対応しています。設定時にのみ読み込まれます
• 仕様 2025-11-25 に準拠した MCP ツールのアノテーション（読み取り専用／破壊的操作のヒント）
• データベース操作でのマルチスキーマ対応

セキュリティ

脅威モデルや情報開示プロセスを含む詳細は、 SECURITY.md に記載されています。要点は次のとおりです。

1. 最小権限のデータベースロールが実質的な境界です。 MCP は既存の認証情報を使用するため、ロールの作成や変更は必要ありません。書き込みを確実に不可能にするのは、専用ロールです。 PostgreSQL 14 以降では、次の設定が出発点になります。

   CREATE ROLE mcp_readonly LOGIN PASSWORD 'change-me';
   GRANT CONNECT ON DATABASE your_database TO mcp_readonly;
   GRANT pg_read_all_data TO mcp_readonly;                          -- adds read privileges
   ALTER ROLE mcp_readonly SET default_transaction_read_only = on;  -- read-only by default
   

   （PostgreSQL 13 以前では、pg_read_all_data の代わりに SELECT を明示的に付与してください。詳しくは SECURITY.md をご覧ください。）スーパーユーザーとして接続すると、サーバーは stderr に警告を出します。読み取り権限の付与によって既存の権限が取り消されることはなく、デフォルト設定は引き続き変更可能です。また、利用可能な関数、所有権、継承された権限も影響します。

2. エンジンが読み取り専用を強制します。 クライアント側での SQL 解析はありません。読み取り専用モードでは、すべての読み取りがロールバックされる BEGIN READ ONLY トランザクションで実行されます。そのため、関数、ビュー、ルールの動作を把握している唯一の存在である PostgreSQL 自体が、あらゆる書き込みを SQLSTATE 25006 で拒否し、ステートメントが行ったセッションの変更を元に戻します。拡張プロトコルは複数コマンドを含む文字列を拒否します。

正確な位置づけ： 読み取り専用トランザクションはロールに加える多層防御であり、ロールの代わりにはなりません。読み取り専用モードは、混乱したモデルやプロンプトインジェクションを受けたモデルによるデータベースへの 書き込み を防ぎますが、クエリが返す行データに含まれるプロンプトインジェクションは防ぎません。このサーバーを本番環境に接続しないでください。レプリカ、スナップショット、または厳密に範囲を限定したロールを使用してください。SECURITY.md をご覧ください。

SSH トンネリング

踏み台（SSH ジャンプホスト）経由でのみアクセスできるデータベースに接続するには、PG_SSH_HOST（および認証とホストキーの検証）を設定します。接続文字列／PG_* フィールドには、踏み台から見えるデータベースを指定します。

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-postgres-server"],
      "env": {
        "DATABASE_URL": "postgres://mcp_readonly:[email protected]:5432/mydb?sslmode=verify-full",
        "PG_SSH_HOST": "bastion.example.com",
        "PG_SSH_USER": "jump",
        "PG_SSH_PRIVATE_KEY": "/home/me/.ssh/id_ed25519",
        "PG_SSH_FINGERPRINT": "SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

変数	デフォルト	説明
PG_SSH_HOST	-	SSH 踏み台ホストです。これを設定するとトンネリングが有効になります。サーバーは、このホストへの SSH トンネル経由でのみデータベースに接続します（以下を参照）。任意の機能であり、オプションの依存関係 ssh2 が必要です。
PG_SSH_PORT	22	SSH 踏み台のポートです。
PG_SSH_USER	-	SSH ユーザー名です。
PG_SSH_PRIVATE_KEY	-	秘密鍵ファイルへのパスです。未設定の場合、認証は ssh と同様に、実行中のエージェント（SSH_AUTH_SOCK）、次にデフォルトの鍵（~/.ssh/id_ed25519、id_rsa、id_ecdsa）の順にフォールバックします。
PG_SSH_PASSPHRASE	-	秘密鍵が暗号化されている場合のパスフレーズです。
PG_SSH_AGENT	-	環境内のエージェント（SSH_AUTH_SOCK）を使用するには true を指定します。または、ソケットパス／Windows 名前付きパイプ（\\.\pipe\openssh-ssh-agent）を明示的に指定します。
PG_SSH_PASSWORD	-	SSH ログインパスワードです。明示的な有効化が必要です。鍵またはエージェントが優先されます。鍵の使用を推奨します。踏み台ではパスワード認証が無効になっていることがよくあります。
PG_SSH_FINGERPRINT	-	固定するホストキーのフィンガープリント（SHA256:...）です。ホストキーの検証は必須で、設定方法はこれに限られます。これがないとトンネルは接続を拒否します（フェイルクローズ）。ssh-keygen -lF host（known_hosts を読み込みます）または ssh-keyscan host | ssh-keygen -lf - で取得してください（以下の信頼に関する注意を参照）。
PG_SSH_KEEPALIVE_INTERVAL	15000	SSH キープアライブの間隔（ミリ秒）です。応答のないキープアライブが 3 回続くとトンネルが切断され、次の呼び出し時に再接続します。

• SSH が変更するのはトランスポートのみです。 読み取り専用の適用、結果サイズの上限、タイムアウト、connect_db の動作は直接接続時と同じで、クエリごとに追加の SQL が送信されることもありません。
• 固定した PG_SSH_FINGERPRINT によるホストキーの検証は必須です。これがないとトンネルは接続しないため、中間者攻撃を仕掛ける踏み台は拒否されます。フィンガープリントは、信頼できる経路から取得してください。信頼性が高い順に以下に示します。
  • 踏み台自体、またはその管理者から取得します。ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub（ネットワークを介しません）。
  • すでに ssh でホストに接続している場合は、既存の ~/.ssh/known_hosts から取得します。ssh-keygen -lF bastion.example.com。
  • ホストから取得します。ssh-keyscan bastion.example.com | ssh-keygen -lf -（ホストが返す内容をそのまま受け入れるため、信頼できるネットワーク上から実行した場合にのみ信頼してください）。
• TLS は実際のデータベースのホスト名を検証します。 verify-full では、証明書はトンネルがローカルでバインドするループバックではなく、データベース自体のホスト名（例：db.internal）と照合されます。また、継承された NODE_TLS_REJECT_UNAUTHORIZED=0 によって検証が無効化されないよう、rejectUnauthorized は固定で有効になります。
• ssh2 はオプションの依存関係です。PG_SSH_HOST が設定された場合にのみ読み込まれるため、直接接続では初期化されません。npm はデフォルトでオプションの依存関係をインストールします。完全にスキップするには npm install --omit=optional を実行してください（直接接続では不要です）。

トンネル経由の接続に失敗すると、固定の SSH_* コードが報告されます。エラー処理を参照してください。

エラー処理

SQL と接続の失敗は、メッセージ、SQLSTATE コード、ヒントを含むツールの結果（isError: true）として返されます。PostgreSQL 独自のサーバーヒントがある場合はそれを使用し、ない場合は次の代替ヒントが適用されます。

コード	意味	最初に確認する項目
28P01	認証に失敗しました	PG_USER / PG_PASSWORD
3D000	データベースが存在しません	PG_DATABASE
42P01	リレーションが見つかりません	list_tables を呼び出します
42703	列が見つかりません	describe_table を呼び出します
57014	クエリがキャンセルされました（タイムアウトまたはキャンセル要求）	タイムアウトの場合は、LIMIT を追加するかクエリを簡略化するか、PG_STATEMENT_TIMEOUT を引き上げます
25006	トランザクションが読み取り専用です	接続元が読み取り専用ロール、レプリカ、サーバーのデフォルト設定、または（query の場合）読み取り専用ラッパーの可能性があります。execute で書き込むには PG_ALLOW_WRITE=true が必要です
ECONNREFUSED / ENOTFOUND	データベースホストに接続できない、または名前を解決できません	PG_HOST / PG_PORT / DATABASE_URL

SSH トンネル経由の場合、失敗には安定した code が含まれます（原因が特定できる場合は、修正すべき設定を示すヒントも含まれます）。そのため、失敗したフェーズを明確に特定できます。

コード	意味	最初に確認する項目
SSH_CONFIG_INVALID	無効な SSH 設定です。形式が不正な PG_SSH_FINGERPRINT も含みます	PG_SSH_* の値
SSH_KEY_INVALID	キーを読み取れない、解析できない、公開鍵である、または正しいパスフレーズがないと復号できない状態です（正しい PG_SSH_PASSPHRASE があれば、暗号化されたキーも使用できます）	PG_SSH_PRIVATE_KEY、PG_SSH_PASSPHRASE
SSH_CONNECT_FAILED	踏み台サーバーに到達できないか、分類できない理由で SSH のセットアップに失敗しました	PG_SSH_HOST、PG_SSH_PORT、到達可能性
SSH_TIMEOUT	踏み台サーバーが時間内に応答しませんでした	ネットワーク／ファイアウォール、PG_CONNECT_TIMEOUT
SSH_AUTH_FAILED	踏み台サーバーが認証を拒否しました	PG_SSH_USER と、使用中のキー／エージェント／パスワード
SSH_HOST_KEY_MISMATCH	ホストキーが PG_SSH_FINGERPRINT と一致しません（値が古い、または MITM の可能性があります）	フィンガープリントを再取得します
SSH_FORWARD_FAILED	トンネルは確立しましたが、踏み台サーバーからデータベースに到達できませんでした	踏み台サーバーから見たデータベースのホストとポート
SSH_CONNECTION_LOST	確立済みのトンネルがセッション中に切断されました	一時的な問題です。次の呼び出しで再接続されます

正常なトンネル経由で発生した本物の PostgreSQL エラーには、SSH コードではなく、独自のコード（例：データベースの認証情報が誤っている場合は 28P01）が使用されます。

0.1.x からの移行

新規インストールでは不要です。0.1.x からの動作変更は次の 2 点です。

1. デフォルトでは読み取り専用です。 execute ツールは常に表示されますが、PG_ALLOW_WRITE=true を設定しない限り、書き込みを拒否します（エラーには必要なフラグが示されます）。また、すべての読み取りはエンジンによって強制される READ ONLY トランザクション内で実行されます。ワークフローでデータベースに書き込む場合は、"PG_ALLOW_WRITE": "true" を設定すると 0.1.x の動作に戻ります。
2. デフォルトでは connect_db は無効です。 実行時の接続切り替え（ツール引数を通じて認証情報を渡すこと）には PG_ENABLE_RUNTIME_CONNECT=true が必要です。設定しない場合、接続の詳細は環境変数からのみ取得されます。

ツール名、パラメーター名、PG_* 変数に変更はありません。すべてのツールで、結果ペイロードは構造化されたコンパクトな JSON になりました（例：query は行の配列だけでなく {rows, rowCount, returnedRows, truncated} を返します）。ツール出力を解析するコードを更新する前に、正確な形式については CHANGELOG.md を参照してください。

ライセンス

MIT