MCP Server for PostgreSQL

PostgreSQL MCP Server

PostgreSQL データベース操作用の MCP サーバーです。Claude Code、Claude Desktop、Cursor、および MCP 対応のあらゆるクライアントで動作します。

言語バージョン

このリポジトリには、TypeScript と Python の実装が含まれています。

バージョン	ディレクトリ	ステータス	MCP プロトコル	インストール
TypeScript	/typescript	✅ 推奨（Smithery）	2026-07-28（SDK v2）	npm install -g @javiagui/postgresql-mcp
Python	/python	✅ 安定版	2026-07-28（SDK v2）	pipx install postgresql-mcp

注：TypeScript バージョンは Smithery のデプロイに使用されます。どちらのバージョンも同じ機能を提供します。

プロトコル互換性：どちらのサーバーも 2026-07-28 リビジョンに対応し、 2世代に対応しています。2025年当時の initialize ハンドシェイクで引き続き接続するクライアントにも 従来どおり応答するため、クライアントをアップグレードする必要はありません。TypeScript パッケージにはパッチ適用済みの Node.js 22.23.4 または 24.22.1 が必要です。 Python パッケージには Python 3.11 以降が必要です（CI ではパッチ適用済みの 3.11.17 と 3.12.15 を使用）。

機能

• クエリ実行：デフォルトで読み取り専用保護を有効にして SQL クエリを実行します
• スキーマの確認：スキーマ、テーブル、ビュー、関数を一覧表示します
• テーブル分析：構造、インデックス、制約、統計情報を確認します
• パフォーマンスツール：クエリを EXPLAIN で解析し、テーブルの健全性を分析します
• セキュリティ優先：SQL インジェクションの防止、認証情報の保護、デフォルトでの読み取り専用
• MCP プロンプト：データベースの確認、クエリの作成、ドキュメント作成のためのガイド付きワークフロー
• MCP リソース：閲覧可能なデータベース構造を Markdown 形式で提供します

クイックスタート

TypeScript（Smithery での使用を推奨）

# Install globally
npm install -g @javiagui/postgresql-mcp

# Or run directly with npx
npx @javiagui/postgresql-mcp

Python

# Install
pipx install postgresql-mcp

# Configure Claude Code
claude mcp add postgres -s user \
  -e POSTGRES_HOST=localhost \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=your_database \
  -- postgresql-mcp

完全なインストールガイド - データベース権限の設定、リモート接続、トラブルシューティングを含みます。

設定

環境変数

変数	必須	デフォルト	説明
POSTGRES_HOST		localhost	データベースのホスト
POSTGRES_PORT		5432	データベースのポート
POSTGRES_USER	✅		データベースのユーザー
POSTGRES_PASSWORD	✅		データベースのパスワード
POSTGRES_DB	✅		データベース名
POSTGRES_SSLMODE		prefer	SSL モード
ALLOW_WRITE_OPERATIONS		false	INSERT/UPDATE/DELETE を有効にします
QUERY_TIMEOUT		30	クエリのタイムアウト（秒）
MAX_ROWS		1000	返される最大行数

複数のデータベース

実際の作業では、複数のデータベースを扱うことがほとんどです。毎回この設定を編集してクライアントを再起動する代わりに、複数の接続を定義し、呼び出しごとにエイリアスで選択できます。

POSTGRES_CONNECTIONS='[
  {"alias":"local","host":"localhost","user":"me","password":"…","database":"app","allowWrite":true},
  {"alias":"staging","url":"postgresql://reader:…@staging.example.com:5432/app"},
  {"alias":"analytics","url":"postgresql://reader:…@warehouse:6543/metrics?sslmode=require","default":true}
]'

• **list_databases**は、設定済みのエイリアスと、ホスト、データベース名、書き込み権限、デフォルトかどうかを返します。認証情報は返されません。
• それ以外のすべてのツールには、エイリアスを指定する任意の**database**引数があります。省略するとデフォルトの接続が使われるため、既存の単一データベース構成は変更せずに引き続き動作します。
• allowWriteは接続ごとに設定され、設定されていない場合はALLOW_WRITE_OPERATIONSが適用されます。本番レプリカは読み取り専用のまま、ローカルデータベースでは書き込みを許可できます。
• default: trueは、databaseが省略されたときに使用する接続を指定します。それ以外の場合は、最初に定義された接続が使われます。デフォルトとして指定できる接続は1つまでです。
• 各接続では、個別のフィールド（host、port、user、password、database、sslmode）またはurl DSNを指定できます。個別のフィールドはDSNより優先されるため、URLを再利用しながら一部を変更できます。
• エイリアスごとに1つのプールが遅延オープンされます。設定されていても使用されないデータベースは、ソケットを開きません。

POSTGRES_CONNECTIONSと通常のPOSTGRES_*変数は相互に排他的です。前者が設定されている場合、後者は無視されるため、どちらが優先されるか迷うことはありません。

認証情報は常に環境変数からのみ取得されます。 database引数で指定するのはエイリアスです。ツール引数としてホスト、ユーザー、パスワード、接続文字列を渡す方法は意図的に用意していません。これにより、シークレットが会話に含まれるのを防ぎます。この仕様はテストで検証されています。

Claude Code CLI

# TypeScript version
claude mcp add postgres -s user \
  -e POSTGRES_HOST=localhost \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=your_database \
  -- npx @javiagui/postgresql-mcp

# Python version
claude mcp add postgres -s user \
  -e POSTGRES_HOST=localhost \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=your_database \
  -- postgresql-mcp

Cursor IDE

~/.cursor/mcp.jsonに追加します。

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["@javiagui/postgresql-mcp"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "your_user",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

利用可能なツール（合計15個）

以下のツールのうちlist_databases以外はすべて、設定済みの接続を指定する任意のdatabase引数を受け取ります。複数のデータベースを参照してください。

クエリの実行

ツール	説明
query	データベースに対して読み取り専用のSQLクエリを実行します
execute	有効な場合、書き込み操作（INSERT／UPDATE／DELETE）を実行します
explain_query	クエリ最適化のためのEXPLAINプランを取得します

スキーマの探索

ツール	説明
list_schemas	データベース内のすべてのスキーマを一覧表示します
list_tables	指定したスキーマ内のテーブルを一覧表示します
describe_table	テーブルの構造（列、型、制約）を取得します
list_views	スキーマ内のビューを一覧表示します
describe_view	ビューの定義と列を取得します
list_functions	関数とプロシージャを一覧表示します

パフォーマンスと分析

ツール	説明
table_stats	テーブルの統計情報（行数、サイズ、肥大化）を取得します
list_indexes	テーブルのインデックスを一覧表示します
list_constraints	制約（PK、FK、UNIQUE、CHECK）を一覧表示します

データベース情報

ツール	説明
get_database_info	データベースのバージョンと接続情報を取得します
search_columns	すべてのテーブルから名前で列を検索します
list_databases	設定済みの接続をエイリアス別に一覧表示し、ホスト、データベース、書き込み権限、デフォルトかどうかを示します。認証情報は返されません。

MCP プロンプト

Claudeが効果的に支援できるようにする、ガイド付きワークフローです。

プロンプト	説明
explore_database	データベースを包括的に探索し、概要を把握します
query_builder	テーブルに対する効率的なクエリの作成を支援します
performance_analysis	テーブルのパフォーマンスを分析し、最適化を提案します
data_dictionary	スキーマのドキュメントを生成します

MCP リソース

参照可能なデータベース構造です。

リソース URI	説明
postgres://schemas	すべてのスキーマを一覧表示します
postgres://schemas/{schema}/tables	スキーマ内のテーブル
postgres://schemas/{schema}/tables/{table}	テーブルの詳細
postgres://database	データベースの接続情報

使用例

設定が完了したら、Claude に次のように依頼してください。

スキーマの確認：

• 「public スキーマ内のすべてのテーブルを一覧表示してください」
• 「users テーブルの構造を説明してください」
• 「どのようなビューが利用できますか？」

クエリ：

• 「orders テーブルから10行表示してください」
• 「先週注文した顧客をすべて検索してください」
• 「ステータス別にグループ化してレコード数を数えてください」

パフォーマンス分析：

• 「orders テーブルにはどのようなインデックスがありますか？」
• 「users テーブルのパフォーマンスを分析してください」
• 「このクエリを説明してください：SELECT * FROM orders WHERE created_at > '2024-01-01'」

ドキュメント：

• 「このデータベースのデータディクショナリを生成してください」
• 「名前に 'email' を含む列はどれですか？」

セキュリティ

この MCP サーバーでは、複数のセキュリティ層を実装しています。

デフォルトで読み取り専用

ALLOW_WRITE_OPERATIONS=true で明示的に有効にしない限り、書き込み操作（INSERT、UPDATE、DELETE）はブロックされます。

SQL インジェクションの防止

• すべてのクエリは実行前に検証されます
• 危険な操作（DROP DATABASE など）は常にブロックされます
• 複数のステートメントは許可されません
• SQL コメントはブロックされます

認証情報の保護

• パスワードは安全な文字列型を使用して保存されます
• 認証情報がログやエラーメッセージに表示されることはありません

クエリの制限

• 結果は MAX_ROWS（デフォルト：1000）で制限されます
• クエリのタイムアウトは QUERY_TIMEOUT で設定できます

開発

TypeScript

cd typescript
npm install
npm run build
npm run dev  # Watch mode

Python

cd python
uv sync
uv run pytest -v --cov=postgres_mcp

テストの実行

# Python unit tests (no database required)
cd python
uv run pytest tests/test_security.py tests/test_settings.py -v

# Integration tests (requires PostgreSQL)
docker-compose up -d
uv run pytest tests/test_integration.py -v

トラブルシューティング

接続の問題

# Verify PostgreSQL is running
pg_isready -h localhost -p 5432

# Test connection with psql
psql -h localhost -U your_user -d your_database

権限が拒否される

データベースユーザーに SELECT 権限があることを確認してください。

GRANT SELECT ON ALL TABLES IN SCHEMA public TO your_user;

MCP サーバーに接続できない

# Check server status
claude mcp get postgres

# Test server directly
postgresql-mcp  # Should wait for MCP messages

リンク

• PyPI パッケージ
• npm パッケージ
• インストールガイド
• GitHub リポジトリ

作者

マルチエージェントのオーケストレーションと MCP 開発を専門とする AI エージェントアーキテクト、Javier Aguilar が開発しました。

ライセンス

MIT