PostgreSQL Model Context Protocol (PG-MCP) Server

PostgreSQL Model Context Protocol（PG-MCP）サーバー

AI エージェント向けに機能を強化した、PostgreSQL データベース用の Model Context Protocol（MCP）サーバーです。

概要

PG-MCP は、PostgreSQL データベース向けの Model Context Protocol のサーバー実装です。MCP のリソース指向アーキテクチャを通じて、AI エージェントが PostgreSQL データベースを検出し、接続し、クエリを実行し、その内容を把握するための包括的な API を提供します。

この実装は、reference Postgres MCP implementation を基盤として、次のような重要な機能強化を加えています。

1. 完全なサーバー実装：本番環境での使用に向けて、SSE トランスポートを備えた完全なサーバーとして構築されています
2. マルチデータベース対応：複数の PostgreSQL データベースに同時に接続できます
3. 充実したカタログ情報：データベースカタログからテーブルやカラムの説明を抽出して公開します
4. 拡張機能のコンテキスト：PostGIS や pgvector などの PostgreSQL 拡張機能について、YAML ベースの詳細な情報を提供します
5. クエリの説明：クエリ実行計画を分析する専用ツールを備えています
6. 堅牢な接続管理：データベース接続の適切なライフサイクル管理と、安全な接続 ID の取り扱いを実現します

機能

接続管理

• 接続ツール：PostgreSQL 接続文字列を登録し、安全な接続 ID を取得します
• 切断ツール：使用後にデータベース接続を明示的に閉じます
• コネクションプーリング：プーリングによって接続を効率的に管理します

クエリツール

• pg_query：接続 ID を使用して読み取り専用の SQL クエリを実行します
• pg_explain：クエリ実行計画を JSON 形式で分析します

スキーマ検出リソース

• 説明付きでスキーマを一覧表示します
• 説明と行数を含めてテーブルを一覧表示します
• データ型と説明を含むカラムの詳細を取得します
• テーブルの制約とインデックスを確認します
• データベース拡張機能を調べます

データアクセスリソース

• テーブルデータのサンプルを取得します（ページネーション対応）
• おおよその行数を取得します

拡張機能のコンテキスト

次のような PostgreSQL 拡張機能に関するコンテキスト情報を内蔵しています。

• PostGIS：空間データ型、関数、使用例
• pgvector：ベクトル類似検索関数とベストプラクティス

追加の拡張機能は、YAML 設定ファイルを使って簡単に追加できます。

インストール

前提条件

• Python 3.13+
• PostgreSQL データベース

Docker を使用する

# Clone the repository
git clone https://github.com/stuzero/pg-mcp.git
cd pg-mcp

# Build and run with Docker Compose
docker-compose up -d

手動インストール

# Clone the repository
git clone https://github.com/stuzero/pg-mcp.git
cd pg-mcp

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install using uv
uv sync --frozen

# Run the server
python -m server.app

使用方法

サーバーのテスト

リポジトリには、サーバーの機能を検証するためのテストスクリプトが含まれています。

# Basic server functionality test
python test.py "postgresql://username:password@hostname:port/database"

# Claude-powered natural language to SQL conversion
python client/claude_cli.py "Show me the top 5 customers by total sales"

claude_cli.py スクリプトには、次の環境変数が必要です。

# .env file
DATABASE_URL=postgresql://username:password@hostname:port/database
ANTHROPIC_API_KEY=your-anthropic-api-key
PG_MCP_URL=http://localhost:8000/sse

AI エージェント向け

エージェントで使用するプロンプトの例：

Use the PostgreSQL MCP server to analyze the database. 
Available tools:
- connect: Register a database connection string and get a connection ID
- disconnect: Close a database connection
- pg_query: Execute SQL queries using a connection ID
- pg_explain: Get query execution plans

You can explore schema resources via:
pgmcp://{conn_id}/schemas
pgmcp://{conn_id}/schemas/{schema}/tables
pgmcp://{conn_id}/schemas/{schema}/tables/{table}/columns

アーキテクチャ

このサーバーは、次の技術を基盤としています。

• MCP：Model Context Protocol の基盤
• FastMCP：MCP 用 Python ライブラリ
• asyncpg：非同期 PostgreSQL クライアント
• YAML：拡張機能のコンテキスト情報に使用

セキュリティ上の考慮事項

• サーバーはデフォルトで読み取り専用モードで動作します（トランザクション設定によって強制されます）
• 接続情報がリソース URL に公開されることはなく、不透明な接続 ID のみが使用されます
• データベースの認証情報を送信する必要があるのは、初回接続時の一度だけです

コントリビューション

コントリビューションを歓迎します。今後の拡張案：

• PostgreSQL 拡張機能のコンテキストファイルの追加
• スキーマのイントロスペクションリソースの追加
• クエリ最適化の提案