PostgreSQL MCP Server

PostgreSQL MCP Server

MCP 対応クライアントから PostgreSQL データベースを調査・クエリするための Python 製 Model Context Protocol（MCP）サーバーです。スキーマの検出、安全な読み取り専用クエリの実行、クエリの説明、テーブルのプレビュー、インデックスの分析、リレーションシップの調査、テーブルメタデータ用の PostgreSQL リソースを提供します。

機能

• public テーブルの一覧表示とテーブルスキーマの確認
• PostgreSQL の読み取り専用トランザクションで読み取り専用 SQL を実行
• 対象クエリを直接実行せずにクエリプランを説明
• 固定の上限でテーブルの行をプレビュー
• 外部キーのリレーションシップとインデックスを確認
• テーブル一覧とスキーマの詳細を受動的な MCP リソースとして公開

安全性モデル

postgresql_execute_read_query は PostgreSQL の読み取り専用トランザクションモードで実行され、POSTGRES_READ_QUERY_LIMIT によって返される行数が制限され、実行後にロールバックされます。また、このサーバーには postgresql_execute_write_query も含まれており、単一の INSERT、UPDATE、DELETE、CREATE、ALTER、DROP、または TRUNCATE ステートメントのみを受け付けます。接続先のデータベースユーザーに権限がある場合、データやスキーマを変更できます。MCP クライアントで書き込み可能なツールを自動承認しないでください。公開または共有して使用する場合は、専用の読み取り専用 PostgreSQL ユーザーでサーバーを実行してください。

要件

• Python 3.11+
• PostgreSQL データベース
• Claude Desktop、Cursor、VS Code などの MCP 対応クライアント、またはその他の MCP ホスト

インストール

PyPI に公開された後は、標準的な Python MCP パッケージと同様にサーバーをインストールまたは実行できます。

uvx mdev-postgresql-mcp-server

ソースからローカルで開発する場合：

git clone https://github.com/musaddiq-dev/postgresql-mcp-server.git
cd postgresql-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

設定

環境ファイルのサンプルをコピーし、データベース接続情報を更新してください。

cp .env.example .env

変数	説明	必須	デフォルト
POSTGRES_HOST	PostgreSQL ホスト	はい	localhost
POSTGRES_PORT	PostgreSQL ポート	はい	5432
POSTGRES_USER	PostgreSQL ユーザー名	はい	なし
POSTGRES_PASSWORD	PostgreSQL パスワード	いいえ	なし
POSTGRES_DB	PostgreSQL データベース名	はい	なし
LOG_LEVEL	stderr に出力する Python ログレベル	いいえ	INFO
POSTGRES_READ_QUERY_LIMIT	読み取りクエリで返される最大行数	いいえ	1000

読み取り専用ユーザーの例：

CREATE USER mcp_readonly WITH PASSWORD 'change-me';
GRANT CONNECT ON DATABASE your_database TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

実行

mdev-postgresql-mcp-server

PyPI 公開前にローカルチェックアウトから実行する場合：

python -m postgresql_mcp_server.server

MCP クライアントの設定

公開済みのインストールでは、uvx の使用を推奨します。stdio を使用する MCP サーバーは、プロトコルメッセージのみを stdout に書き込む必要があります。このサーバーは Python のロギングを通じてログを stderr に書き込みます。

Claude Desktop / Cursor / Windsurf / Cline

ほとんどの MCP クライアントは、次の mcpServers JSON 形式を受け付けます。

{
  "mcpServers": {
    "postgresql": {
      "command": "uvx",
      "args": ["mdev-postgresql-mcp-server"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "mcp_readonly",
        "POSTGRES_PASSWORD": "change-me",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

このリポジトリでローカル開発する場合は、代わりにインストール済みのコンソールスクリプトのパスを使用してください。

{
  "mcpServers": {
    "postgresql": {
      "command": "/absolute/path/to/postgresql-mcp-server/.venv/bin/mdev-postgresql-mcp-server",
      "args": [],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "mcp_readonly",
        "POSTGRES_PASSWORD": "change-me",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

Claude Code CLI

claude mcp add postgresql \
  --env POSTGRES_HOST=localhost \
  --env POSTGRES_PORT=5432 \
  --env POSTGRES_USER=mcp_readonly \
  --env POSTGRES_PASSWORD=change-me \
  --env POSTGRES_DB=your_database \
  -- uvx mdev-postgresql-mcp-server

VS Code MCP

VS Code の MCP 設定では、同じコマンド／引数／環境変数の形式を使用します。

{
  "servers": {
    "postgresql": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mdev-postgresql-mcp-server"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "mcp_readonly",
        "POSTGRES_PASSWORD": "change-me",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

ツール

ツール	用途	安全性
postgresql_list_tables	public のベーステーブルを一覧表示	読み取り専用
postgresql_describe_table	テーブルのカラムとメタデータを表示	読み取り専用
postgresql_execute_read_query	読み取り専用トランザクションモードで、件数を制限して SQL を実行	読み取り専用
postgresql_execute_write_query	承認された単一の変更 SQL ステートメントを実行してコミット	破壊的
postgresql_explain_query	単一のクエリに対する PostgreSQL の EXPLAIN 出力を返す	読み取り専用
postgresql_get_database_summary	データベースのバージョンとテーブル数を返す	読み取り専用
postgresql_get_relationships	外部キーのリレーションシップを確認	読み取り専用
postgresql_analyze_indexes	インデックスとサイズを確認	読み取り専用
postgresql_preview_table	テーブルから最大 10 行を返す	読み取り専用
postgresql_search_sql_definitions	public の SQL ルーチン／関数を検索	読み取り専用

リソース

• postgres://list_tables は public テーブル名を返します。
• postgres://schema/{table_name} はテーブルの生成済みスキーマステートメントを返します。

スモークチェック

データベースを使用せずに、次のコマンドで構文を確認します。

python -m py_compile src/postgresql_mcp_server/server.py

設定済みのデータベースがある場合は、サーバーを起動し、MCP クライアントを使って list_tables を呼び出します。

配布

このサーバーは、標準的な Python MCP 配布経路を通じて公開されています。

• PyPI パッケージ：mdev-postgresql-mcp-server
• MCP Registry 名：io.github.musaddiq-dev/postgresql-mcp-server
• ランタイムのヒント：uvx
• トランスポート：stdio

この README の先頭にある mcp-name マーカーは、MCP Registry の所有権確認に必要です。ユーザーは、ローカルの MCP クライアント設定で uvx mdev-postgresql-mcp-server を使用することを推奨します。

セキュリティに関する注意事項

• 認証情報が含まれる .env や MCP クライアント設定をコミットしないでください。
• 最小権限のデータベースユーザーを使用してください。
• execute_write_query は破壊的な操作として扱い、MCP クライアントでユーザーの明示的な承認を必須にしてください。
• 書き込み可能なツールを実行する前に、生成された SQL を確認してください。

ライセンス

MIT