Postgres Connector MCP

🚀 PostgreSQL MCP Server

PostgreSQL MCP Serverは、PostgreSQLデータベースを照会するためのMCP（Model Context Protocol）サーバーです。MCP互換のクライアントを通じて、SQLクエリを実行し、テーブルの詳細を表示し、データベース接続を管理することができます。

✨ 主な機能

• データベース接続：認証を伴ってPostgreSQLデータベースに接続します。
• SQL実行：セキュリティ検証付きでSELECTクエリを実行します。
• 接続テスト：データベースの接続状態をテストします。

📦 インストール

Claude Desktop

以下の手順でインストールしてください。

ステップ1：MCPサーバーのダウンロード

このリポジトリのルートディレクトリにあるpostgres-connector.mcpbファイルをダウンロードします。

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

1. Claude Desktopを開きます。
2. 設定 > 機能に移動します。
3. 「拡張機能をインストール」 をクリックし、postgres-connector.mcpbファイルを選択します。

スクリーンショットのプレースホルダー：.mcpbファイルのインストール

ステップ3：データベース接続の設定

インストール後、PostgreSQLコネクタがClaude Desktopに表示され、デフォルトの環境変数をデータベースの詳細で設定することができます。

スクリーンショットのプレースホルダー：環境変数を表示するデータベース設定インターフェース

ステップ4：データベース接続のテスト

「test the database connection」というクエリを送信します。

📚 ドキュメント

必要なデータベース設定

PostgreSQLデータベースには、以下の情報を提供する必要があります。

これらの環境変数は、Claude Desktopで拡張機能をインストールした後、拡張機能の設定パネルで自動的に設定できるようになります。

利用可能なツール

1. PostgreSQL接続のテスト

ツール：test-postgres-connection

データベース接続をテストし、現在の設定を表示します（セキュリティ上の理由でパスワードは非表示）。

出力例：

✅ データベース接続に成功しました！

設定:
{
  "host": "localhost",
  "port": "5432",
  "database": "myapp_production",
  "username": "postgres",
  "password": "***hidden***"
}

接続テスト結果: [
  {
    "test": 1
  }
]

2. すべてのテーブルを取得

ツール：get-all-tables

データベースのpublicスキーマ内のすべてのテーブルのリストを取得します。

出力例：

[
  {
    "table_name": "users"
  },
  {
    "table_name": "orders"
  },
  {
    "table_name": "products"
  },
  {
    "table_name": "categories"
  }
]

3. SQLクエリの実行

ツール：execute-sql-query

セキュリティ検証付きでデータベースにSELECTクエリを実行します。

入力：

• sql：実行するSQLクエリ（SELECT文のみ）

使用例：

SELECT id, name, email FROM users LIMIT 5;

出力例：

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
]

セキュリティと安全性

SQLクエリの検証

PostgreSQL MCPサーバーには、以下のセキュリティ対策が含まれています。

• 読み取り専用操作：SELECT文のみが許可されます。
• 危険なキーワードのブロック：DROP、DELETE、TRUNCATE、ALTER、CREATE、INSERT、UPDATE操作は自動的にブロックされます。
• 文レベルの検証：各SQL文は個別に検証されます。
• 安全なエラーハンドリング：データベースエラーは捕捉され、安全に表示されます。

ベストプラクティスとして、postgresコネクタが使用する読み取り専用のデータベースユーザーを作成することをお勧めします。

ブロックされる操作

セキュリティ上の理由から、以下のSQL操作は許可されません。

• DROP（テーブル/データベースの削除）
• DELETE（データの削除）
• TRUNCATE（テーブルのクリア）
• ALTER（構造の変更）
• CREATE（新しいオブジェクトの作成）
• INSERT（データの追加）
• UPDATE（データの変更）

💻 使用例

データベーステーブルの取得

get-all-tablesツールを使用して、データベーススキーマ内のすべてのテーブルを取得します。

クエリの実行

execute-sql-queryツールを使用してSELECT文を実行します。

SELECT * FROM users LIMIT 10;

📚 トラブルシューティング

接続問題

問題：「Database connection failed」

• 確認事項：ホスト、ポート、データベース名、ユーザー名、パスワードを確認してください。
• 確認事項：PostgreSQLサーバーが実行中で、アクセス可能であることを確認してください。
• 確認事項：データベースユーザーに必要な権限があることを確認してください。

問題：「Connection timeout」

• 確認事項：データベースサーバーがファイアウォールの後ろにある可能性があります。
• 確認事項：ホストアドレスとポート番号が正しいことを確認してください。
• 確認事項：データベースサーバーへのネットワーク接続を確認してください。

クエリ問題

問題：「Dangerous operation detected」

• 原因：SELECT文以外の文を実行しようとしています。
• 解決策：セキュリティ上の理由から、SELECTクエリのみが許可されています。

問題：「Query execution failed」

• 確認事項：SQL構文が正しいことを確認してください。
• 確認事項：参照しているテーブルと列が存在することを確認してください。
• 確認事項：データベースユーザーがテーブルにSELECT権限を持っていることを確認してください。

設定問題

問題：MCPサーバーがClaude Desktopクライアントに表示されない

• 解決策：Claude Desktopを再起動してください。
• 確認事項：.mcpbファイルが正しくインストールされていることを確認してください。
• 確認事項：Claude Desktopのコンソールにエラーメッセージがないか確認してください。

問題：環境変数が表示されない

• 解決策：インストール後にClaude Desktopを再起動してください。
• 確認事項：設定 > 機能で拡張機能が有効になっていることを確認してください。

問題：データベース設定を構成できない

• 解決策：必要なすべての環境変数が入力されていることを確認してください。
• 確認事項：データベースの資格情報が正しいことを確認してください。

🔧 技術詳細

システム要件

• PostgreSQLデータベース（バージョン9.0以上）
• PostgreSQLサーバーへのネットワークアクセス

依存関係

• Node.jsランタイム
• PostgreSQLクライアントライブラリ
• MCP（Model Context Protocol）フレームワーク

プロジェクト構造

postgres-connector/
├── src/
│   └── server.ts          # メインのMCPサーバー実装
├── package.json           # Node.jsの依存関係
├── manifest.json          # MCP拡張機能のマニフェスト
├── icon.png              # 拡張機能のアイコン
└── postgres-connector.mcpb # コンパイルされた拡張機能バンドル

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

作者

Marty Markenson

• メール：martyamark@gmail.com
• LinkedIn：Marty Markenson

ヘルプが必要ですか？ このリポジトリで問題を開くか、martymarkensonまでお問い合わせください。