postgres-mcp

Claude（または任意のMCP互換クライアント）を利用して、任意のPostgresデータベースに対して読み取り専用のクエリを実行するための、汎用かつ再利用可能なMCPサーバーです。特定のスキーマについての知識はなく、list_tables、describe_table、run_sql は、information_schema と一般的なjsonbイントロスペクションだけを使って動作するので、コードを変更せずに任意のPostgresデータベースに適用できます。

セキュリティモデル

多層防御を備えた、独立した2つのレイヤーです。

1. DBレベル: サーバーは、SELECTのみが許可されたロールとして接続します。たとえクエリが書き込みを試みようとしても、書き込むことはできません。このロールは setup_reader_role.sql で作成します。

2. アプリレベル: run_sql() は、単純な SELECT（または WITH ... SELECT）以外をすべて拒否し、200行の上限を強制し、ステートメントのタイムアウトを5秒に設定します。これらはすべて、データベースに実際にアクセスする前に実行されるフェイルファストなチェックです。

Related MCP server: pg-mcp

セットアップ

1. 対象のデータベースに読み取り専用ロールを作成します:

   • setup_reader_role.sql を開き、パスワードのプレースホルダーと <your_db_name> を実際の値に置き換え、対象のデータベースに対して一度実行します（例: psql またはデータベースプロバイダのSQLコンソールを使用）。

2. このディレクトリ内の .env ファイルに接続文字列を設定します:

   DATABASE_URL=postgresql://mcp_reader:yourpassword@host:5432/yourdb
   ANTHROPIC_API_KEY=sk-ant-...

   (ANTHROPIC_API_KEY は chat.py でのみ必要です。MCPサーバー自体の実行には必要ありません。)

3. 依存関係をインストールします:

   pip install -r requirements.txt

ローカルテスト

まず、MCPクライアントを介さずにクエリレイヤーを直接テストします:

python chat.py "what tables do I have?"

次に、Inspectorで実際のMCPサーバーとしてテストします:

fastmcp dev inspector mcp_server.py

もしInspectorのNode.jsツールチェーンで問題が発生する場合（以前にもありました）、代わりにHTTPでサーバーを直接起動し、FastMCP Python クライアントからアクセスする方法に切り替えてください:

fastmcp run mcp_server.py --transport http --port 8000

from fastmcp import Client
import asyncio

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        print(await client.call_tool("list_tables", {}))

asyncio.run(main())

デプロイ（Prefect Horizon）

FastMCPのホスティング型デプロイプラットフォームは現在 Prefect Horizon と呼ばれています（以前は「FastMCP Cloud」でした。過去にも名称変更されているので、以下の手順を進める前に、gofastmcp.com/deployment に現在の名称・URLを再確認してください。また変わっている可能性があります）。

1. このリポジトリをGitHubにプッシュします — 先に実際のリモートが存在している必要があります（まだ設定していない場合は、このREADMEの下部にあるgitコマンドを参照してください）。

2. 現在のプラットフォームのサイト（執筆時点では horizon.prefect.io）にアクセスし、GitHubアカウントでサインインします。

3. このリポジトリを接続します。

4. デプロイを設定します:

   • エントリーポイント: mcp_server.py:mcp — この :mcp の部分は、ファイル内でサーバーオブジェクトが代入される変数名です（mcp_server.py 内の mcp = FastMCP(...) の行を参照してください）。もし変数名を変更したりファイルを移動したりした場合は、このエントリーポイントの文字列もそれが一致するように正確に更新しなければなりません。

   • 認証: これをオンにしてください。claude.ai や Claude Desktop のような対話型MCPクライアントは、接続するために実在するOAuthディスカバリエンドポイントを必要とします。認証を有効にしていないサーバーは、直接のAPI呼び出しやFastMCP Python クライアントでテストしても正常に動作する場合でも、それらのクライアントでは動作しません。

   • 環境変数: プラットフォームのダッシュボード上で DATABASE_URL を追加してください。これはこのプロジェクトのローカルにある .env ファイルとは別物で、.env は読み込まれません。デプロイされたサーバーがデータベースにアクセスできるようにするには、値をダッシュボードに直接入力する必要があります。

5. デプロイして、発行されたサーバーURLをコピーします。https://<your-server-name>.fastmcp.app/mcp のような形になります（正確なドメインは異なる場合があります — 実際にプラットフォームに表示されるものを使用してください）。

6. ほかの場所に接続する前に、まずプラットフォームに組み込みのInspector/テストツールでテストしてください。まずそこで list_tables を呼び出します。引数が必要ないため、デプロイしたサーバーが実際にデータベースに到達できることを確認する最速の方法です。

claude.ai への接続

1. claude.ai → Settings → Connectors → Add custom connector の順に移動します。

2. 前のデプロイ手順で取得したサーバーURLを貼り付けます。

3. 表示されるOAuthプロンプトを完了します。

4. 新規チャットを開始します（コネクタを追加する前から存在していたチャットではなく、そのチャットで コネクタを有効にします）。

5. 「どのようなテーブルがありますか？」のような簡単な質問でテストします。

6. 後で新しいツールを追加して表示されない場合、何かが壊れていると決めつける前に、コネクタの設定にある「ツールを更新」を試してください。これは既知のキャッシュ動作であって、バグではありません。

制限

このサーバーは本当にスキーマに依存しませんが、制限がないわけではありません。

• Postgres固有。 jsonb_object_keys() と、Postgresのカタログ構文（information_schema など）を使用しています。MySQLやSQLiteを対象にする場合は、接続文字列を変えるだけではダメーで、db_tools.pyのコードを実際に変更する必要があります。

• スキーマ非依存なことは、データベースごとのセットアップが不要なことを意味するではありません。 新しいターゲットデータベースには、専用読み取り専用ロール（setup_reader_role.sql）と、そのデータベースに向けた専用デプロイ（少なくとも専用のDATABASE_URL）がやはり必要です。つまり、複数データベースを透過的に提供する単一サーバではありません。

Gitセットアップ

まだgitの履歴をせずにこのコードから始める場合:

git init
git add .
git commit -m "Initial commit: generic read-only Postgres MCP server"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main