License: MIT

mcp-postgres

PostgreSQL用MCPサーバー。Model Context Protocolを通じて、AIエージェントにスキーマインテリジェンス、クエリ実行、DBAツール機能を提供します。

汎用的なデータベースMCPサーバーとは異なり、mcp-postgresはPostgresネイティブです。テーブルやカラムのコメントを抽出し、Postgres固有のカタログビューを理解し、インデックス分析を提供します。また、LLMに無制限のデータベースアクセス権を与えないよう、アクセスレベルを設定可能です。

特徴

スキーマインテリジェンス

スキーマ、テーブル、ビューをサイズと行数付きで一覧表示
テーブルの詳細説明：カラム、型、制約、インデックス、外部キー
COMMENT ON メタデータの抽出 — カラムの意味に関するセマンティックなコンテキストをLLMに提供
データベース全体で名前やコメントによるオブジェクト検索

クエリ実行

自動行制限付きの読み取り専用 query ツール
アクセスレベルによって制御される書き込み可能な execute ツール
人間が読みやすい出力形式の EXPLAIN ANALYZE

DBAツール

テーブル統計：ライブ/デッドタプル、肥大化率、バキューム履歴、スキャンパターン
インデックス分析：使用統計、未使用インデックスの検出、不足インデックスの提案
データベースの健全性：接続数、キャッシュヒット率、長時間実行クエリ、スループット

安全性

4つのアクセスレベル：readonly、readwrite、admin、unrestricted
SQLステートメントの分類（SELECT、DML、DDL、admin）と強制適用
stderrへの監査ログ出力（JSON形式、クエリごとに1エントリ）

クイックスタート

npx mcp-postgres --connection-string "postgres://user:pass@localhost:5432/mydb"

または環境変数を使用する場合：

DATABASE_URL="postgres://user:pass@localhost:5432/mydb" npx mcp-postgres

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-postgres",
        "--connection-string",
        "postgres://user:pass@localhost:5432/mydb"
      ]
    }
  }
}

Claude Code

プロジェクトの .mcp.json に追加します：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "mcp-postgres"],
      "env": {
        "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb"
      }
    }
  }
}

ツール

ツール	説明	アクセス
`list_schemas`	テーブル数とサイズを含むスキーマ一覧	readonly
`list_tables`	コメント、行数、サイズを含むテーブル一覧	readonly
`describe_table`	カラム、インデックス、FK、コメントを含むテーブル詳細	readonly
`search_objects`	名前またはコメントによるオブジェクト検索	readonly
`query`	SELECTクエリの実行	readonly
`execute`	INSERT/UPDATE/DELETE/CREATE等の実行	可変
`explain_query`	読みやすい出力形式の EXPLAIN (ANALYZE)	readonly*
`table_stats`	テーブル統計、肥大化、バキューム情報	readonly
`index_analysis`	インデックス使用状況、未使用インデックス、不足インデックスのヒント	readonly
`database_health`	接続数、キャッシュ率、長時間クエリ、肥大化	readonly

* analyze=true を指定した explain_query はクエリを実行するため、ステートメントのアクセスレベルに従います。

リソース

URI	説明
`postgres://schema/{name}`	スキーマの完全なDDL（コメント付きのCREATE TABLE文）
`postgres://extensions`	インストール済みのPostgreSQL拡張機能

プロンプト

プロンプト	説明
`explore-database`	ガイド付きデータベース探索 — スキーマ、テーブル、リレーションシップ
`optimize-query`	EXPLAIN、インデックス、推奨事項を用いた低速クエリの分析
`health-check`	包括的なデータベース健全性評価

設定

CLIオプション

--connection-string  PostgreSQL connection URL
--access-level       readonly|readwrite|admin|unrestricted (default: readonly)
--row-limit          Max rows returned per query (default: 500)
--schema             Default schema filter (default: public)
--audit              Enable query audit logging to stderr

環境変数

変数	説明
`DATABASE_URL`	PostgreSQL接続URL
`POSTGRES_URL`	代替接続URL
`MCP_POSTGRES_ACCESS_LEVEL`	アクセスレベルのオーバーライド
`MCP_POSTGRES_ROW_LIMIT`	行制限のオーバーライド

アクセスレベル

レベル	SELECT	INSERT/UPDATE/DELETE	CREATE/ALTER/DROP	TRUNCATE/DROP DATABASE
`readonly`	はい	いいえ	いいえ	いいえ
`readwrite`	はい	はい	いいえ	いいえ
`admin`	はい	はい	はい	いいえ
`unrestricted`	はい	はい	はい	はい

デフォルトは readonly です。必要な最小限のレベルを使用してください。

監査ログ

--audit で有効にします。すべてのツール呼び出しをJSONとしてstderrに記録します：

{"timestamp":"2026-04-03T12:00:00.000Z","tool":"query","sql":"SELECT * FROM users","statementType":"select","accessLevel":"readonly","allowed":true,"durationMs":12,"rowCount":42}

stderrをファイルにパイプしてキャプチャします：mcp-postgres --audit 2>audit.log

アーキテクチャ

src/
├── index.ts             Entry point and CLI
├── server.ts            MCP server setup
├── config.ts            Configuration parsing
├── db/
│   ├── pool.ts          Connection pool management
│   └── query.ts         Query execution with timing
├── tools/
│   ├── schema.ts        Schema exploration tools
│   ├── query.ts         Query execution tools
│   └── performance.ts   DBA and health tools
├── resources/
│   └── schema.ts        Schema DDL resources
├── prompts/
│   └── index.ts         Prompt templates
└── safety/
    ├── classifier.ts    SQL statement classification
    ├── access.ts        Access level enforcement
    └── audit.ts         Audit logging

開発

npm install
npm test           # run tests
npm run build      # compile TypeScript
npm run dev -- --connection-string "postgres://..."  # run in dev mode

ライセンス

MIT

mcp-postgres

mcp-postgres

特徴

クイックスタート

Claude Desktop

Claude Code

ツール

リソース

プロンプト

設定

CLIオプション

環境変数

アクセスレベル

監査ログ

アーキテクチャ

開発

ライセンス

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API