Postgres MCP

English | 🌐 Português

Postgres MCP 🔌 PostgreSQL 用のネイティブ MCP サーバーです。実行時に .env から認証情報を読み込み、柔軟なキーのマッピング、設定可能なツール選択、そしてデフォルトで読み取り専用モードを提供します。

---

✨ 機能

ほとんどの LLM は、テーブル名を推測したり、カラム名をでっち上げたり、失敗したり機密データを漏えいさせたりする可能性のあるクエリを作成したりして、データベースとやり取りします。Postgres MCP は、データベースにアクセスする前に実際の構造を把握できるよう、構造化された安全なインターフェースを LLM に提供します。

@modelcontextprotocol/sdk と pg で構築されており、次の機能を提供します。

• 🧠 セマンティックナレッジグラフ - 実際のスキーマから構築された、スキーマ、テーブル、カラム、外部キー、推定されるリレーション、リスクレベル、業務ドメインの完全なマップを LLM が利用できます。推測で作られたものではありません
• 🛡️ デフォルトで読み取り専用 - 明示的に有効にしない限り、書き込み、DDL、任意の SQL は実行されません。pg_classify_query_risk を使うと、クエリを実行する前に安全性を確認できます
• 🔐 実行時の認証情報解決 - 起動時に .env から認証情報を読み込みます。機密情報を mcp.json に保存する必要はありません
• 🎯 明示的なツール選択 - tool=<name> 引数を使って各ツールを個別に有効化するため、LLM には公開するものだけが表示されます

---

📋 必要条件

• ⚙️ Node.js >= 18
• 📄 データベース認証情報を記載した .env ファイル（プロジェクトツリー内の任意の場所。詳しくは .env ファイルの検出を参照）

---

🚀 インストール

このパッケージの利用方法は 2 通りあります。ワークフローに最適な方法を選んでください。

オプション 1 - インストール不要（npx を使用。クイックスタートにおすすめ）

インストールは不要です。npx が必要に応じてパッケージをダウンロードして実行します。確認プロンプトをスキップするには、最初の引数に -y を追加してください。

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@edelciomolina/postgres-mcp"
      ],
      "env": {
        "MCP_KEY_HOST":    "DB_HOST",
        "MCP_KEY_PORT":    "DB_PORT",
        "MCP_KEY_NAME":    "DB_NAME",
        "MCP_KEY_SSLMODE": "DB_SSLMODE",
        "MCP_KEY_USER":    "DB_USER",
        "MCP_KEY_PASS":    "DB_PASS"
      }
    }
  }
}

これにより、デフォルトの読み取り専用ツールセットでサーバーが起動します。tool= 引数は不要です。書き込み可能なツールを有効にする方法については、書き込み可能なツールを参照してください。

💡 Supabase、Neon、Railway など、接続文字列のみを提供するプラットフォームを使用していますか？ MCP_KEY_URL を DATABASE_URL（またはプラットフォームで使用されている変数名）に指定してください。サーバーは URL を優先し、個別の変数は無視します。詳しくはURL を使った接続を参照してください。

---

オプション 2 - VS Code からインストール（MCP 拡張機能マーケットプレイス）

VS Code では、ターミナルを使わずに、エディターから MCP サーバーを直接検索してインストールできます。

1. コマンドパレットを開きます（Mac では Cmd+Shift+P、Windows/Linux では Ctrl+Shift+P）。
2. MCP: Add Server を実行します。
3. 「Browse MCP Servers」（または、VS Code のバージョンによっては 「From registry」）を選択します。
4. postgres-mcp または edelciomolina を検索します。
5. Postgres MCP を選択し、手順に従います。VS Code によって mcp.json にエントリが自動的に追加されます。

💡 MCP サーバーのパネルは、Copilot のチャットアイコン → MCP サーバーの管理から開くこともできます。いつでもサーバーを検索、有効化、無効化できます。

インストール後、生成された .vscode/mcp.json のエントリを編集し、以下の使用方法セクションに示すように、tool= 引数と env キーのマッピングを追加してください。

---

🚀 VS Code での使用方法（mcp.json）

読み取り専用（デフォルト - tool= 引数は不要です）：

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["@edelciomolina/postgres-mcp"],
      "env": {
        "MCP_KEY_HOST":    "DB_HOST",
        "MCP_KEY_PORT":    "DB_PORT",
        "MCP_KEY_NAME":    "DB_NAME",
        "MCP_KEY_SSLMODE": "DB_SSLMODE",
        "MCP_KEY_USER":    "DB_USER",
        "MCP_KEY_PASS":    "DB_PASS"
      }
    }
  }
}

書き込みツールを使用する場合（明示的なオプトインが必要です）：

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@edelciomolina/postgres-mcp",
        "tool=pg_manage_schema",
        "tool=pg_manage_indexes"
      ],
      "env": {
        "POSTGRES_MCP_ALLOW_WRITE": "true",
        "MCP_KEY_HOST":    "DB_HOST",
        "MCP_KEY_PORT":    "DB_PORT",
        "MCP_KEY_NAME":    "DB_NAME",
        "MCP_KEY_SSLMODE": "DB_SSLMODE",
        "MCP_KEY_USER":    "DB_USER",
        "MCP_KEY_PASS":    "DB_PASS"
      }
    }
  }
}

⚠️ 書き込み可能なツールを使用するには、env に POSTGRES_MCP_ALLOW_WRITE=true が必要です。設定されていない場合、サーバーは起動時に終了します。

プロジェクトのルートにある対応する .env ファイル：

DB_HOST=db.your-project.supabase.co
DB_PORT=5432
DB_NAME=postgres
DB_SSLMODE=require
DB_USER=readonly_user
DB_PASS=your_password

---

⚙️ mcp.json の設定方法

🗝️ env - 認証情報キーのマッピング

env ブロックには、実際の認証情報は含まれません。各 MCP_KEY_* を、.env ファイル内の変数名に対応付けます。

env のキー	対応する .env の変数	値の例
MCP_KEY_URL	DATABASE_URL	postgresql://user:pass@host:5432/db?sslmode=require
MCP_KEY_HOST	DB_HOST	db.example.supabase.co
MCP_KEY_PORT	DB_PORT	5432
MCP_KEY_NAME	DB_NAME	postgres
MCP_KEY_SSLMODE	DB_SSLMODE	require
MCP_KEY_USER	DB_USER	readonly_user
MCP_KEY_PASS	DB_PASS	secret

優先順位： MCP_KEY_URL（または DATABASE_URL）が設定されている場合、サーバーは URL を直接使用し、個別の認証情報キーを無視します。

この間接的なマッピングにより、.env では任意の変数名を使用できます。命名規則の異なる複数のサービス間で .env を共有する場合に便利です。

🔧 args - tool= プレフィックスによるツールの選択

有効にする MCP ツールはそれぞれ、tool=<name> の形式で個別の引数として宣言します。

"args": [
  "-y",
  "@edelciomolina/postgres-mcp",
  "tool=pg_manage_schema",
  "tool=pg_manage_indexes"
]

これにより、ツールの一覧を mcp.json で直接明示的に記述し、監査可能にできます。隠れた設定ファイルはありません。🔍

---

🔗 URL による接続（DATABASE_URL）

個別の認証情報に加えて、Supabase、Neon、Railway などのプラットフォームで標準的な形式の完全な接続文字列を指定できます。

.env：

DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require

mcp.json：

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@edelciomolina/postgres-mcp"],
      "env": {
        "MCP_KEY_URL": "DATABASE_URL"
      }
    }
  }
}

MCP_KEY_URL でマッピングされた変数は、他のキー（MCP_KEY_HOST、MCP_KEY_PORT など）よりも優先されます。URL が設定されている場合、他の変数は無視されます。

プラットフォームで異なる名前（例：DB_URL）が使われている場合は、マッピングを変更してください。

"MCP_KEY_URL": "DB_URL"

---

🛡️ 読み取り専用がデフォルトの理由

すべての tool= 引数を省略すると、サーバーは厳選された読み取り専用セットで起動します。データを取得、分析、説明できるツールのみが含まれ、データを変更するツールは含まれません。

✅ デフォルトで含まれるツール（読み取り専用）：

pg_execute_query       pg_manage_query        pg_inspect_schema
pg_get_setup_instructions                     pg_analyze_database
pg_monitor_database                           pg_debug_database
pg_inspect_database_graph                     pg_describe_table_semantics
pg_find_related_tables                        pg_classify_query_risk

💡 pg_execute_query は、データベースに問い合わせる前に、INSERT、UPDATE、DELETE、DDL、ANALYZE、VACUUM、EXPLAIN ANALYZE、その他の書き込み／メンテナンスコマンドを拒否します。

💡 pg_inspect_schema は、読み取り専用のスキーマ調査（get_info、get_enums）を提供します。DDL 操作には、明示的にオプトインして pg_manage_schema を使用してください。

⚠️ デフォルトでは除外されます。使用するには tool= 引数と POSTGRES_MCP_ALLOW_WRITE=true の両方が必要です：

ツール	操作
pg_manage_schema	CREATE TABLE、ALTER TABLE、CREATE TYPE
pg_manage_indexes	CREATE INDEX、DROP INDEX、REINDEX
pg_manage_constraints	ADD CONSTRAINT、DROP CONSTRAINT
pg_manage_functions	CREATE FUNCTION、DROP FUNCTION
pg_manage_triggers	CREATE TRIGGER、DROP TRIGGER、有効化／無効化
pg_manage_rls	RLS の有効化／無効化、CREATE/ALTER/DROP POLICY
pg_manage_users	CREATE/DROP/ALTER USER、GRANT、REVOKE
pg_execute_mutation	INSERT / UPDATE / DELETE / UPSERT
pg_execute_sql	トランザクションをサポートする任意の SQL

---

📍 .env ファイルの検出

サーバーは次の順序で .env ファイルを解決します。

1. env-file=<path> 引数 - cwd からの相対パス。何よりも優先されます
2. 上位ディレクトリの検索 - cwd から始めて、.env が見つかるかファイルシステムのルートに達するまで、各親ディレクトリを検索します

.env が見つからない場合、サーバーは明確なエラーメッセージを表示して終了します。

モノレポとサブフォルダー

VS Code が MCP プロセスを起動するとき、cwd は通常、ワークスペースのルートです。.env がサブフォルダー（例：functions/.env）にある場合は、env-file= を使って明示的に指定してください：

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@edelciomolina/postgres-mcp",
        "env-file=functions/.env"
      ],
      "env": {
        "MCP_KEY_HOST":    "DB_HOST",
        "MCP_KEY_PORT":    "DB_PORT",
        "MCP_KEY_NAME":    "DB_NAME",
        "MCP_KEY_SSLMODE": "DB_SSLMODE",
        "MCP_KEY_USER":    "DB_USER",
        "MCP_KEY_PASS":    "DB_PASS"
      }
    }
  }
}

💡 上位ディレクトリの検索により、一般的なケースは自動的に処理されます。明示的に制御する必要がある場合（CI、モノレポ、Docker のバインドマウント）は、env-file= を使用してください。

---

🧰 利用可能なツール

読み取り専用（デフォルトで有効）

ツール	説明
pg_execute_query	書き込みおよび複数ステートメントのガード付き SELECT / COUNT / EXISTS
pg_manage_query	EXPLAIN プラン、遅いクエリの分析、pg_stat_statements
pg_inspect_schema	スキーマ情報と ENUM 型（読み取り専用の調査）
pg_get_setup_instructions	プラットフォームごとのセットアップ手順
pg_analyze_database	パフォーマンス、設定、ストレージの分析
pg_monitor_database	接続、クエリ、ロック、レプリケーションのリアルタイム監視
pg_debug_database	接続、ロック、パフォーマンス、レプリケーションの診断
pg_inspect_database_graph	データベースの完全なナレッジグラフを構築します。スキーマ、テーブル、列、FK、インデックス、推定された関連、ビジネスドメインが含まれます
pg_describe_table_semantics	意味的なコンテキストを含めてテーブルを説明します。リスクレベル、列の役割、機密列、関連テーブルが含まれます
pg_find_related_tables	明示的な FK と推定された命名パターンを使って、指定したテーブルに関連するテーブルを検索し、経路を説明します
pg_classify_query_risk	クエリを実行せずにリスク（safe / warning / review / blocked）を分類します

書き込み可能（tool= 引数と POSTGRES_MCP_ALLOW_WRITE=true によるオプトイン）

ツール	説明
pg_manage_schema	スキーマ情報、テーブルの作成・変更、ENUM の管理
pg_manage_indexes	インデックスの一覧表示、作成、削除、再インデックス、使用状況の分析
pg_manage_constraints	制約と外部キーの一覧表示、作成、削除
pg_manage_functions	関数とプロシージャの一覧表示、作成、削除
pg_manage_triggers	トリガーの一覧表示、作成、削除、有効化・無効化
pg_manage_rls	行レベルセキュリティポリシー
pg_manage_users	ユーザー権限、ユーザーの作成・削除・変更、権限の付与・取り消し
pg_execute_mutation	パラメーター化クエリによる INSERT / UPDATE / DELETE / UPSERT
pg_execute_sql	任意の SQL 実行（トランザクションのサポートは任意）

---

🧠 セマンティックレイヤー

4 つの pg_*_graph / pg_*_semantics / pg_*_risk ツールは、実行時にデータベースのインメモリナレッジグラフを構築します。これにより、LLM はスキーマ、テーブル、列、外部キー、推論された関連性、リスクレベル、ビジネスドメインを含む構造化されたマップを利用できます。データに対するクエリは一切実行されません。

推論されたフィールド（列の意味的な役割、テーブルの推定型、推論された関連性）にはすべて明確なタグが付けられるため、LLM はスキーマ上の事実ではなく、ヒントとして扱うことができます。

オプション設定（mcp-config.json）

セマンティックレイヤーとセキュリティ制限を調整するには、.env の隣に mcp-config.json ファイルを配置します。すべてのフィールドは任意です。ファイルを省略すると、安全なデフォルト設定が適用されます。

{
  "security": {
    "defaultLimit": 100,
    "maxLimit": 1000,
    "blockedSchemas": ["pg_catalog", "information_schema"],
    "blockedTables": [],
    "requireLimit": true
  },
  "semanticLayer": {
    "enabled": true,
    "inferRelationsWithoutForeignKeys": true,
    "inferBusinessEntities": true,
    "sensitiveKeywords": ["password", "secret", "token", "api_key", "ssn", "hash"]
  }
}

---

🏗️ アーキテクチャ

MCP クライアント、プロキシ、PostgreSQL 間の通信フローを詳しく確認するには、完全なシーケンス図を含む ARCHITECT.md を参照してください。

---

📄 ライセンス

MIT © Edelcio Molina