PostgreSQL MCP Server (Model Context Protocol)

PostgreSQL MCP サーバー

FastMCP を利用した Model Context Protocol サーバーです。AI アシスタント（Claude、Cursor など）に PostgreSQL データベースへの完全かつ構造化されたアクセスを提供します。ユーザーが SQL の知識を持っている必要はありません。

---

概要

このサーバーは、stdio トランスポートを介して PostgreSQL データベースを MCP リソース（読み取り専用ビュー）と MCP ツール（読み書き操作）のセットとして公開します。MCP 互換の AI クライアントであれば接続してスキーマを調べ、自然言語でデータ操作を実行できます。

Claude / Cursor / any MCP client
        │  stdio (MCP protocol)
        ▼
 postgres_mcp_server.py   (FastMCP layer — resources & tools)
        │  async
        ▼
 postgres_manager.py      (asyncpg connection pool)
        │
        ▼
  PostgreSQL Database

---

機能

カテゴリ	機能
スキーマ	すべてのテーブルの一覧表示、カラム定義の確認
読み取り	フィルター、並べ替え、行数制限を指定した選択
書き込み	行の挿入、更新、削除
DDL	テーブルの作成と削除
生 SQL	任意のクエリを実行
安全性	全体を通してパラメーター化クエリを使用（SQL インジェクションなし）
ログ記録	ツール／リソース呼び出しごとに構造化ログを stdout に出力

---

MCP リソース

リソースは、AI クライアントがサブスクライブできる読み取り専用の URI アドレス指定可能なデータフィードです。

URI	説明
postgres://tables	データベース内のすべてのテーブルの JSON リスト
postgres://schema/{table_name}	テーブルのカラム名、型、制約
postgres://data/{table_name}	テーブルの先頭 100 行（安全なプレビュー）

---

MCP ツール

ツールは、AI がユーザーに代わって呼び出せる操作です。

execute_query

任意の生 SQL 文を実行し、結果を JSON として取得します。

query: str  — the SQL to run

create_table

カスタムのカラム定義で新しいテーブルを作成します。

table_name: str
columns:    [{"name": "id", "type": "SERIAL PRIMARY KEY"}, ...]

drop_table

テーブルを完全に削除します。

table_name: str

insert_data

テーブルに 1 行挿入します。

table_name: str
data:       {"column": value, ...}

update_data

条件に一致する行を更新します。

table_name:       str
data:             {"column": new_value, ...}
condition:        "id = %s"
condition_params: [42]

delete_data

条件に一致する行を削除します。

table_name:       str
condition:        "status = %s"
condition_params: ["inactive"]

select_data

任意のフィルター、並べ替え、ページネーションを指定してテーブルをクエリします。

table_name:       str
columns:          ["id", "name"]          (optional, default: *)
condition:        "age > %s"              (optional)
condition_params: [18]                    (optional)
order_by:         "created_at DESC"       (optional)
limit:            100                     (optional, default: 100)

---

前提条件

• Python 3.8+
• PostgreSQL サーバー（ローカルまたはリモート）
• uv パッケージマネージャー（推奨）— または pip
• MCP 互換の AI クライアント（Claude Desktop、Cursor など）

---

インストール

# 1. Clone the repository
git clone https://github.com/VivekMalipatel/Postgres_MCP_Server.git
cd Postgres_MCP_Server

# 2. Create and activate a virtual environment
python -m venv .mcp
source .mcp/bin/activate        # macOS / Linux
# .mcp\Scripts\activate         # Windows

# 3. Install dependencies
pip install -r requirements.txt

---

設定

プロジェクトのルートに .env ファイルを作成します。

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=your_database
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password

---

Claude Desktop への接続

次のブロックを Claude Desktop の MCP 設定ファイルに追加します。
（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "PostgreSQL MCP": {
      "command": "/absolute/path/to/.mcp/bin/uv",
      "args": [
        "run",
        "--with", "mcp[cli]",
        "--with", "asyncpg",
        "--with", "httpx",
        "--with", "python-dotenv",
        "--with", "psycopg2-binary",
        "mcp",
        "run",
        "/absolute/path/to/postgres_mcp_server.py"
      ],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

/absolute/path/to/ はすべて、使用する環境の実際のパスに置き換えてください。
.env ファイルを使用する場合は、env ブロックを省略できます。

---

手動での実行（stdio）

python postgres_mcp_server.py

サーバーが起動し、MCP プロトコルメッセージを stdin で待ち受けます。通常の使用では、上記の設定を通じて AI クライアントがサーバーを自動的に起動します。

---

依存関係

パッケージ	用途
mcp[cli]	MCP プロトコルと FastMCP フレームワーク
asyncpg	高性能な非同期 PostgreSQL ドライバー
psycopg2-binary	同期 PostgreSQL ドライバー（フォールバック）
python-dotenv	.env ファイルの読み込み
httpx	非同期 HTTP クライアント（ツールから利用可能）
uvicorn	ASGI サーバー（将来の HTTP トランスポート向け）
uv	高速な Python パッケージランナー

---

プロジェクト構成

Postgres_MCP_Server/
├── postgres_mcp_server.py   # FastMCP server — resources, tools, lifespan
├── postgres_manager.py      # Async DB manager (connection pool, CRUD)
├── requirements.txt
└── .env                     # (create this — not committed)

---

ライセンス

MIT — 自由に使用、変更、配布できます。