PostgreSQL MCP Serverのセットアップ方法 (2026年版)

PostgreSQL MCP サーバーのセットアップ方法 (2026年版)

PostgreSQL MCP サーバーを使用すると、Claude などの AI アシスタントが PostgreSQL データベースに直接クエリを実行し、スキーマの検査、テーブルのリスト表示、データの分析をすべて自然な会話を通じて行えるようになります。クエリ結果を手動でチャットウィンドウにコピーする代わりに、Claude にデータベースへの直接的かつ制御されたアクセス権を付与します。このガイドでは、セットアップ、構成、およびセキュリティのベストプラクティスについて説明します。

PostgreSQL MCP サーバーとは？

MCP (Model Context Protocol) は、AI アシスタントを外部ツールやデータソースに接続するための Anthropic のオープン標準です。PostgreSQL MCP サーバーは、データベースを Claude が呼び出し可能な一連のツールとして公開します。

ツール	説明
query	読み取り専用の SQL クエリを実行する
list_tables	スキーマ内のすべてのテーブルをリスト表示する
describe_table	テーブルの列名、型、制約を取得する
list_schemas	データベース内のすべてのスキーマをリスト表示する
get_table_stats	行数と基本的な統計情報を取得する

Claude が PostgreSQL MCP サーバーに接続されると、「今月の売上上位10人の顧客は誰ですか？」といった自然言語の質問を投げることができ、Claude が SQL を記述・実行して結果を提示します。

前提条件

• PostgreSQL 12 以降が動作しており、アクセス可能であること
• Node.js 18 以降 (MCP サーバー用)
• Claude Desktop または Claude Code (MCP 対応クライアント)
• 適切な権限を持つ PostgreSQL ユーザー

バージョンの確認：

psql --version
# psql (PostgreSQL) 16.x

node --version
# v20.x.x or higher

ステップ 1: 読み取り専用のデータベースユーザーを作成する

MCP サーバーをスーパーユーザーや書き込み権限を持つアカウントで接続しないでください。専用の読み取り専用ユーザーを作成します。

-- 管理者として PostgreSQL に接続
psql -U postgres

-- 読み取り専用ロールを作成
CREATE ROLE mcp_reader WITH LOGIN PASSWORD 'your_secure_password';

-- データベースへの接続権限を付与
GRANT CONNECT ON DATABASE your_database TO mcp_reader;

-- スキーマの使用権限を付与
GRANT USAGE ON SCHEMA public TO mcp_reader;

-- 既存のすべてのテーブルに SELECT 権限を付与
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_reader;

-- 今後作成されるテーブルにも自動的に SELECT 権限を付与
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO mcp_reader;

-- オプション: 追加のスキーマへのアクセス権を付与
GRANT USAGE ON SCHEMA analytics TO mcp_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA analytics TO mcp_reader;

ユーザーが読み取り専用であることを確認します。

psql -U mcp_reader -d your_database -c "SELECT 1;"
# 成功するはずです

psql -U mcp_reader -d your_database -c "DROP TABLE users;"
# 権限拒否で失敗するはずです

ステップ 2: PostgreSQL MCP サーバーのインストール

コミュニティによっていくつかの PostgreSQL MCP サーバーパッケージがメンテナンスされています。最も一般的なのは @modelcontextprotocol/server-postgres です。

# グローバルにインストール
npm install -g @modelcontextprotocol/server-postgres

# または npx を使用 (インストール不要)
npx @modelcontextprotocol/server-postgres

ステップ 3: Claude Desktop の設定

Claude Desktop の設定に PostgreSQL MCP サーバーを追加します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://mcp_reader:your_secure_password@localhost:5432/your_database"
      ]
    }
  }
}

環境変数の使用 (推奨)

設定ファイルに認証情報を記述するのを避けるには：

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://mcp_reader:your_secure_password@localhost:5432/your_database"
      }
    }
  }
}

リモートデータベースへの接続

リモートデータベースの場合は、SSL を指定した完全な接続文字列を使用します。

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://mcp_reader:password@db.example.com:5432/mydb?sslmode=require"
      }
    }
  }
}

ステップ 4: Claude Code の設定

Claude Code (CLI) を使用している場合は、プロジェクトの .claude/settings.json に MCP サーバーを追加します。

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://mcp_reader:password@localhost:5432/your_database"
      }
    }
  }
}

または、~/.claude/settings.json でグローバルに設定して、すべてのプロジェクトで使用可能にします。

ステップ 5: 再起動と確認

設定を保存した後：

1. Claude Desktop を完全に終了します (ウィンドウを閉じるだけでなく、アプリを終了させてください)。
2. Claude Desktop を再度開きます。
3. データベースアイコンまたは MCP ツールインジケーターを探します。
4. Claude に質問します：「データベースにはどんなテーブルがありますか？」

Claude がテーブルのリストを返せば成功です。そうでない場合は、後述のトラブルシューティング セクションを確認してください。

クエリの例

接続されると、自然言語で Claude に質問できます。

スキーマの探索

"public スキーマ内のすべてのテーブルを行数とともにリストアップして"

"users テーブルの構造を教えて。すべての列とその型を表示して"

データ分析

"2026年1月の総売上上位10製品は何ですか？"

"過去30日間の日次新規登録トレンドを表示して"

複雑なクエリ

"過去7日間に登録したけれど、まだ購入していないユーザーをすべて見つけて。
メールアドレスと登録日を含めてください。"

"過去6ヶ月間のアクティブユーザーの月次成長率を計算して"

Claude が適切な SQL を生成し、MCP サーバー経由で実行し、読みやすい形式で結果を提示します。

セキュリティのベストプラクティス

対策	理由	方法
読み取り専用ユーザーを使用する	誤ったデータ変更を防止する	GRANT SELECT のみに制限する
特定のスキーマに制限する	データ露出を最小限にする	GRANT USAGE ON SCHEMA を選択的に行う
コネクションプーリングを使用する	接続不足を防止する	PgBouncer または組み込みプールを使用
ステートメントタイムアウトを設定する	長時間実行クエリを防止する	ALTER ROLE mcp_reader SET statement_timeout = '30s'
機密テーブルを除外する	個人情報 (PII) や認証情報を保護する	特定のテーブルの SELECT 権限を剥奪する
SSL を使用する	転送中のデータを暗号化する	接続文字列に ?sslmode=require を追加
クエリを監査する	Claude が何にアクセスしているか監視する	MCP ロールに対して log_statement = 'all' を有効にする

機密テーブルへのアクセス制限

-- 機密データを含むテーブルへのアクセス権を剥奪
REVOKE SELECT ON TABLE user_credentials FROM mcp_reader;
REVOKE SELECT ON TABLE payment_methods FROM mcp_reader;
REVOKE SELECT ON TABLE api_keys FROM mcp_reader;

-- あるいは、安全な列のみを公開するビューを作成
CREATE VIEW safe_users AS
  SELECT id, username, created_at, last_login
  FROM users;

GRANT SELECT ON safe_users TO mcp_reader;

クエリ制限の設定

-- MCP ユーザーに30秒のタイムアウトを設定
ALTER ROLE mcp_reader SET statement_timeout = '30s';

-- 返される行数を制限するためのメモリ設定
ALTER ROLE mcp_reader SET work_mem = '64MB';

応用：カスタム PostgreSQL MCP サーバー

より詳細な制御が必要な場合は、追加のロジックを組み込んだカスタム MCP サーバーを構築できます。

// custom-pg-mcp.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import pg from "pg";

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  max: 5,
  statement_timeout: 30000
});

const server = new Server({
  name: "custom-postgres",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "query",
      description: "Execute a read-only SQL query",
      inputSchema: {
        type: "object",
        properties: {
          sql: { type: "string", description: "SQL SELECT query" }
        },
        required: ["sql"]
      }
    }
  ]
}));

server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "query") {
    const sql = args.sql.trim();

    // SELECT と WITH (CTE) ステートメントのみを許可
    if (!/^(SELECT|WITH)\b/i.test(sql)) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries allowed" }],
        isError: true
      };
    }

    // 危険なキーワードをブロック
    const blocked = /\b(DROP|DELETE|UPDATE|INSERT|ALTER|TRUNCATE|GRANT|REVOKE)\b/i;
    if (blocked.test(sql)) {
      return {
        content: [{ type: "text", text: "Error: Blocked keyword detected" }],
        isError: true
      };
    }

    try {
      const result = await pool.query(sql);
      return {
        content: [{
          type: "text",
          text: JSON.stringify(result.rows, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Query error: ${error.message}` }],
        isError: true
      };
    }
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

トラブルシューティング

事象	原因	解決策
"Connection refused"	PostgreSQL が起動していない、またはポートが違う	pg_isready -h localhost -p 5432 を確認
"Authentication failed"	パスワードまたはユーザー名が違う	psql で直接認証情報を確認
MCP サーバーが反映されない	設定ファイルのエラー	JSON の構文を確認し、Claude Desktop を再起動
"Permission denied for table"	GRANT 権限の不足	GRANT SELECT ON ALL TABLES... を再実行
クエリがタイムアウトする	statement_timeout が未設定	ロールに対して statement_timeout を設定
"SSL required"	リモート DB が SSL を要求している	接続文字列に ?sslmode=require を追加
クエリが遅い	インデックス不足またはテーブルが巨大	インデックスを追加するか、クエリで LIMIT を使用する

結論

PostgreSQL MCP サーバーは、AI を介したデータベース操作のあり方を一変させます。SQL クライアントとチャットウィンドウを行き来する代わりに、Claude が直接データを照会し、スキーマを探索し、結果の分析を支援できるようになります。重要なのは、読み取り専用ユーザーと制限されたテーブルアクセスによって、適切なセキュリティを構築することです。

データ駆動型のアプリケーションを構築しており、分析データを動画プレゼンテーションに変換したり、チャートベースのコンテンツを生成したりするなど、AI 生成のビジュアルコンテンツも必要なチームには、Hypereal AI がデータパイプラインを補完する動画生成、画像合成、トーキングアバター作成のための API を提供しています。