PostgreSQL Full Access MCP Server

PostgreSQL フルアクセス MCP サーバー

このプロジェクトは、Syahiid Kamil によるオリジナルの mcp-postgres-full-access を独立して保守・拡張したフォークです。

PostgreSQL データベースへの完全な読み書きアクセスを提供する、強力な Model Context Protocol サーバーです。読み取り専用の公式 MCP PostgreSQL サーバーとは異なり、この拡張実装では、適切なトランザクション管理と安全制御のもと、LLM がデータベースの内容を照会するだけでなく変更することもできます。

目次

• 機能
  • 完全な読み書きアクセス
  • 豊富なスキーマ情報
  • 高度な安全制御
• ツール
  • execute_query
  • execute_dml_ddl_dcl_tcl
  • execute_maintenance
  • execute_commit
  • execute_rollback
  • list_tables
  • describe_table
  • list_schemas
• リソース
• Claude Desktop での使用
  • Claude Desktop との統合
  • 重要：「1 回だけ許可」を使用した安全対策
• 環境変数
• Claude での完全なデータベースアクセスの使用
• セキュリティに関する考慮事項
  • データベースユーザーの権限
  • 安全に使用するためのベストプラクティス
• Docker
• ライセンス
• 公式 PostgreSQL MCP サーバーとの比較

🌟 機能

完全な読み書きアクセス

• DML 操作（INSERT、UPDATE、DELETE）を安全に実行します
• DDL を使用してデータベースオブジェクトを作成、変更、管理します
• 明示的なコミットによるトランザクション管理
• 安全のためのタイムアウトと自動ロールバック保護

豊富なスキーマ情報

• 詳細な列のメタデータ（データ型、説明、最大長、NULL 許容性）
• 主キーの特定
• 外部キーの関係
• 型と一意性フラグを含むインデックス情報
• テーブルの行数の推定
• テーブルと列の説明（利用可能な場合）

高度な安全制御

• SQL クエリの分類（DQL、DML、DDL、DCL、TCL）
• 安全なクエリに対する読み取り専用実行の強制
• すべての操作を分離されたトランザクション内で実行
• トランザクションのタイムアウトを自動監視
• 設定可能な安全上限
• ユーザーによる明示的な確認を伴う、2 段階のトランザクションコミット処理

🔧 ツール

• execute_query

  • 読み取り専用の SQL クエリ（SELECT 文）を実行します
  • 入力：sql（文字列）：実行する SQL クエリ
  • すべてのクエリは READ ONLY トランザクション内で実行されます
  • 結果には実行時間のメトリクスとフィールド情報が含まれます

• execute_dml_ddl_dcl_tcl

  • データ変更操作（INSERT、UPDATE、DELETE）またはスキーマ変更（CREATE、ALTER、DROP）を実行します
  • 入力：sql（文字列）：実行する SQL 文
  • 設定可能なタイムアウトを使用して、自動的にトランザクション内で実行されます
  • 明示的なコミットに使用するトランザクション ID を返します
  • 重要な安全機能：実行後に会話が終了するため、ユーザーはコミットまたはロールバックを決定する前に結果を確認できます

• execute_maintenance

  • VACUUM、ANALYZE、CREATE DATABASE などのメンテナンスコマンドを、トランザクション外で実行します
  • 入力：sql（文字列）：実行する SQL 文。VACUUM、ANALYZE、または CREATE DATABASE である必要があります
  • 実行時間のメトリクスを含む結果オブジェクトを返します

• execute_commit

  • ID を指定してトランザクションを明示的にコミットします
  • 入力：transaction_id（文字列）：コミットするトランザクションの ID
  • コミットまたはロールバック後のクリーンアップを安全に処理します
  • 変更をデータベースに永続的に適用します

• execute_rollback

  • ID を指定してトランザクションを明示的にロールバックします
  • 入力：transaction_id（文字列）：ロールバックするトランザクションの ID
  • すべての変更を安全に破棄し、リソースをクリーンアップします
  • 変更を確認したうえで適用しないと決定した場合に便利です

• list_tables

  • データベース内のすべてのテーブルの包括的な一覧を取得します
  • 列数とテーブルの説明が含まれます
  • 入力パラメーターは不要です

• describe_table

  • 特定のテーブル構造の詳細情報を取得します
  • 入力：table_name（文字列）：説明を取得するテーブルの名前
  • 主キー、外部キー、インデックス、列の詳細を含む完全なスキーマ情報を返します

• list_schemas

  • データベース内のすべてのスキーマの一覧を取得します
  • 入力パラメーターは不要です
  • 名前、所有者、テーブル数を含むスキーマの配列を返します

📊 リソース

サーバーは、データベーステーブルの拡張スキーマ情報を提供します。

• テーブルスキーマ（postgres://<host>/<table>/schema）
  • 各テーブルの詳細な JSON スキーマ情報
  • 完全な列メタデータ、主キー、制約が含まれます
  • データベースメタデータから自動的に検出されます

🚀 Claude Desktop での使用

Claude Desktop との連携

このサーバーを Claude Desktop で使用するには、次の手順に従ってください。

1. まず、システムに Node.js がインストールされていることを確認します

2. npx を使用してパッケージをインストールするか、プロジェクトに追加します

3. claude_desktop_config.json を編集して Claude Desktop を設定します（通常、macOS では ~/Library/Application Support/Claude/ にあります）。

{
  "mcpServers": {
    "postgres-full": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-postgres-full-access-extended",
        "postgresql://username:password@localhost:5432/database"
      ],
      "env": {
        "TRANSACTION_TIMEOUT_MS": "60000",
        "MAX_CONCURRENT_TRANSACTIONS": "5",
        "PG_STATEMENT_TIMEOUT_MS": "30000"
      }
    }
  }
}

4. データベース接続文字列を、実際の PostgreSQL 接続情報に置き換えます
5. Claude Desktop を完全に再起動します

重要：「Allow Once」を使用した安全な運用

Claude がデータベースへの変更をコミットしようとすると、Claude Desktop で承認を求められます。

承認する前に、SQL の変更内容を必ず慎重に確認してください！

安全に使用するためのベストプラクティス：

• コミット操作では、必ず「Always allow」ではなく「Allow once」をクリックします
• 承認する前に、トランザクションの SQL を慎重に確認します
• 権限を制限したデータベースユーザーの使用を検討します
• このサーバーを初めて試す場合は、可能であればテスト用データベースを使用します

この「Allow once」方式により、必要に応じて Claude にデータ管理タスクを支援させながら、データベースへの望ましくない変更を防ぐための完全な制御を維持できます。

⚙️ 環境変数

Claude Desktop の設定で環境変数を指定すると、サーバーの動作をカスタマイズできます。

"env": {
  "TRANSACTION_TIMEOUT_MS": "60000",
  "MAX_CONCURRENT_TRANSACTIONS": "5"
}

主な環境変数：

• TRANSACTION_TIMEOUT_MS：トランザクションのタイムアウト（ミリ秒単位、デフォルト：15000）

  • トランザクションにもっと時間が必要な場合は、この値を大きくしてください
  • この時間を超えたトランザクションは、安全のため自動的にロールバックされます

• MAX_CONCURRENT_TRANSACTIONS：同時に実行できるトランザクションの最大数（デフォルト：10）

  • より慎重に運用するには、この値を小さくしてください
  • 値を大きくすると、より多くの書き込み操作を同時に実行できます

• ENABLE_TRANSACTION_MONITOR：トランザクションモニターを有効または無効にします（「true」または「false」、デフォルト：「true」）

  • 放置されたトランザクションを監視し、自動的にロールバックします
  • 無効にする必要が生じることはほとんどありません

• PG_STATEMENT_TIMEOUT_MS：SQL クエリの実行タイムアウト（ミリ秒単位、デフォルト：30000）

  • 1 つの SQL ステートメントを実行できる時間を制限します
  • クエリの暴走を防ぐための重要な安全機能です

• PG_MAX_CONNECTIONS：PostgreSQL の最大接続数（デフォルト：20）

  • データベースの接続数上限を超えないようにすることが重要です

• MONITOR_INTERVAL_MS：停滞したトランザクションを確認する頻度（デフォルト：5000）

  • 通常、調整する必要はありません

🔄 Claude でデータベースへのフルアクセスを使用する

このサーバーを使うと、承認を得たうえで Claude が PostgreSQL データベースの読み取りと書き込みを行えます。会話の例をいくつか紹介します。

例：新しいテーブルの作成とデータの追加

あなた：「id、name、price、inventory の列を持つ新しい products テーブルが必要です」

Claude：データベースを分析してクエリを作成します

CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    inventory INTEGER DEFAULT 0
);

Claude Desktop でこの操作の承認を求められます

あなた：内容を確認し、「Allow once」をクリックします

Claude：「products テーブルを作成しました。サンプルデータも追加しますか？」

あなた：「はい、サンプル商品を 5 件追加してください」

Claude：INSERT ステートメントを作成し、承認を求めます 内容を確認し、「Allow once」で承認します

例：安全なクエリによるデータ分析

あなた：「価格が高い順に、上位 3 件の商品を教えてください」

Claude：読み取り専用クエリを自動的に実行します 結果を表示します

安全なワークフロー

データベースを変更する操作には、次の 2 段階の手順が適用されます。これが主な安全機能です。

1. Claude がリクエストを分析し、SQL を準備します
2. 読み取り専用操作（SELECT）の場合、Claude が自動的に実行します
3. 書き込み操作（INSERT、UPDATE、DELETE、CREATE など）の場合：
   • Claude がトランザクション内で SQL を実行し、会話を終了します
   • 結果を確認します
   • 新しい会話で「Yes」と返答するとコミット、「No」と返答するとロールバックされます
   • Claude Desktop に変更内容が正確に表示され、許可を求められます
   • 特定の操作を許可するには、「Allow once」をクリックします
   • Claude が操作を実行し、結果を返します

これにより、変更がデータベースに永続的に適用される前に、複数回確認する機会が得られます。

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

書き込みアクセスを許可して Claude をデータベースに接続する場合：

データベースユーザーの権限

重要： 適切な権限を持つ専用のデータベースユーザーを作成してください。

-- Example of creating a restricted user (adjust as needed)
CREATE USER claude_user WITH PASSWORD 'secure_password';
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_user;
GRANT INSERT, UPDATE, DELETE ON TABLE table1, table2 TO claude_user;
-- Only grant specific permissions as needed

安全に使用するためのベストプラクティス

1. 書き込み操作を確認する際は、必ず「Allow once」を使用してください

   • データベースの変更に対して「Always allow」を選択しないでください
   • 時間をかけて SQL を慎重に確認してください

2. このツールを初めて試す際は、テスト用データベースに接続してください

   • 最初のテストでは、データベースのコピーやバックアップを使用することを検討してください

3. データベースユーザーの権限は、必要なものだけに制限してください

   • スーパーユーザーや管理者アカウントの使用は避けてください
   • 可能であれば、テーブルごとに権限を付与してください

4. 本格的に使用する前に、データベースをバックアップしてください

5. LLM に公開すべきでない機密データを共有しないでください

6. 承認する前に、すべての SQL 操作を確認してください

   • テーブル名を確認します
   • 列名とデータを確認します
   • WHERE 句が適切か確認します
   • トランザクションが適切に処理されているか確認します

Docker

サーバーは Docker コンテナで簡単に実行できます。

# Build the Docker image
docker build -t mcp-postgres-full-access .

# Run the container
docker run -i --rm mcp-postgres-full-access "postgresql://username:password@host:5432/database"

macOS で Docker を使用する場合は、ホストネットワークに接続するために host.docker.internal を使用してください。

docker run -i --rm mcp-postgres-full-access "postgresql://username:[email protected]:5432/database"

📄 ライセンス

この MCP サーバーは MIT ライセンスの下でライセンスされています。

💡 公式 PostgreSQL MCP サーバーとの比較

機能	このサーバー	公式 MCP PostgreSQL サーバー
読み取りアクセス	✅	✅
書き込みアクセス	✅	❌
スキーマの詳細	強化	基本
トランザクションのサポート	タイムアウトを明示的に設定	読み取り専用
インデックス情報	✅	❌
外部キーの詳細	✅	❌
行数の推定値	✅	❌
テーブルの説明	✅	❌

作者

Syahiid Nur Kamil が作成（@syahiidkamil）

kamusis が拡張（@kamusis）

---

Copyright © 2025 kamusis. All rights reserved.