PostgreSQL Model Context Protocol (PG-MCP) Server

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

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

pg-mcp プロジェクトの詳細はこちらをご覧ください：

https://stuzero.github.io/pg-mcp/

概要

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

この実装は、Postgres のリファレンス MCP 実装を基盤として、以下の重要な機能を追加・拡張しています。

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 データベース（1 つ以上）

Docker を使用する

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

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

手動インストール

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

# Install dependencies and create a virtual environment ( .venv )
uv sync

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 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 example-clients/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

A comprehensive database description is available at this resource:
pgmcp://{conn_id}/

アーキテクチャ

このサーバーは、以下を基盤として構築されています。

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

セキュリティに関する考慮事項

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

コントリビューション

コントリビューションを歓迎します。今後の拡張候補は以下のとおりです。

• PostgreSQL 拡張機能のコンテキストファイルの追加
• スキーマを調査するリソースの追加
• クエリ最適化の提案