モデルコンテキストプロトコル PostgreSQL サーバー

このプロジェクトは、PostgreSQLデータベースに接続するモデルコンテキストプロトコル（MCP）サーバーを実装します。これにより、AIモデルは標準化されたプロトコルを介してデータベースとやり取りできるようになります。

特徴

• 接続プールを使用してPostgreSQLデータベースに接続します

• AIモデルのインタラクションのためのモデルコンテキストプロトコルを実装します

• データベーススキーマ情報をリソースとして提供する

• 再試行ロジックを使用してSQLクエリを実行できます

• 接続エラーを適切に処理します

Related MCP server: PostgreSQL MCP Server

前提条件

• Node.js 20以上

• PostgreSQLデータベース

• データベースのアクセス資格情報

インストール

1. このリポジトリをクローンする

2. 依存関係をインストールします:

npm install

構成

サーバーは、プロジェクトのルートディレクトリにある.envファイルからデータベースの認証情報を読み取ります。データベースの認証情報は、JSON 文字列としてDB_CREDENTIALS環境変数に追加する必要があります。

1. プロジェクト ルートに.envファイルを作成します。

touch .env

2. 実際のデータベース資格情報を含む次の行を追加します。

export DB_CREDENTIALS='{"DB_USER":"your-username","DB_PASSWORD":"your-password","DB_HOST":"your-host","DB_PORT":"5433","DB_NAME":"your-database"}'

シェル設定ファイルへのフォールバック

.envファイルが存在しないか、資格情報変数が見つからない場合、サーバーは次の順序でシェル構成ファイル内の資格情報を自動的に検索します。

1. ~/.zshrc

2. ~/.bashrc

3. ~/.bash_profile

4. ~/.profile

これは、カーソル MCP 環境など、シェル構成ファイルが自動的にソース化されない環境で特に役立ちます。

シェル構成ファイルのいずれかで資格情報を設定するには:

1. 好みのシェル設定ファイルを開きます。例:

nano ~/.zshrc
# or
nano ~/.bashrc

2. 実際のデータベース資格情報を含む次の行を追加します。

export DB_CREDENTIALS='{"DB_USER":"your-username","DB_PASSWORD":"your-password","DB_HOST":"your-host","DB_PORT":"5433","DB_NAME":"your-database"}'

.envファイルが利用できない場合、サーバーはこれらの資格情報を自動的に検出して使用します。

カスタム資格情報変数

サーバーの起動時に--credentials-varフラグを使用して、 DB_CREDENTIALSの代わりにカスタム環境変数名を使用することもできます。

node server.js --credentials-var MY_CUSTOM_DB_CREDS

この場合、代わりに.envファイルでMY_CUSTOM_DB_CREDSを定義します。

オプションの組み合わせ

必要に応じて、さまざまなコマンドライン オプションを組み合わせることができます。

# Use custom credentials and enable verbose mode
node server.js --credentials-var MY_CUSTOM_DB_CREDS --verbose

# Short form also works
node server.js -c MY_CUSTOM_DB_CREDS -v

使用法

MCP サーバーを起動します。

# Directly with Node.js
node server.js

# Or with npm
npm start

ログオプション

デフォルトでは、サーバーはサイレントモードで実行され、エラーメッセージのみが表示されます。すべてのログメッセージを表示するには、verboseフラグを使用します。

# With verbose logging
node server.js --verbose

# Or with npm
npm start -- --verbose

短いフラグ-vを使用することもできます。

node server.js -v

サーバーは次のことを行います。

1. データベース接続をテストする

2. stdioトランスポートを使用してMCPサーバーを起動します

3. AIモデルからのリクエストを処理する

カーソルとの統合

このサーバーは、モデル コンテキスト プロトコル (MCP) をサポートし、Cursor AI と統合されます。

自動構成

このプロジェクトには、Cursor 内での自動セットアップ用に事前構成された.cursor/mcp.jsonファイルが含まれています。

手動設定

このサーバーを手動でカーソルに追加するには:

1. カーソル設定→機能→MCPに移動します

2. 「+新しいMCPサーバーを追加」をクリックします

3. 次の詳細を入力してください。

   • 名前: Postgres MCP

   • タイプ: stdio

   • コマンド: node /full/path/to/server.js

MCP と Cursor の統合の詳細については、公式ドキュメントを参照してください。

利用可能なツール

サーバーは AI モデルに次のツールを提供します。

• query : 再試行ロジックを使用してSQLクエリを実行する

リソース

サーバーはデータベース テーブルをリソースとして公開し、AI モデルが次のことを実行できるようにします。

• データベース内のすべてのテーブルを一覧表示する

• 各テーブルのスキーマ情報を表示する

エラー処理

サーバーには以下が含まれます。

• 接続再試行ロジック

• 詳細なエラーログ

• 正常なシャットダウン処理

トラブルシューティング

接続の問題

1. データベース接続に失敗しました

   • PostgreSQLが実行中かどうか確認する: pg_isready -h localhost -p 5433

   • .envファイル内の資格情報が正しいことを確認してください

   • IP アドレスがデータベースにアクセスできることを確認してください (pg_hba.conf を確認してください)

   • 資格情報を確認するには、 psqlなどの別のツールで接続してみてください。

2. 環境変数の問題

   • .envファイルがプロジェクトのルートディレクトリにあることを確認してください

   • DB_CREDENTIALSのJSON構造が有効であることを確認します

   • JSON文字列に余分なスペースや改行がないことを確認する

   • 次のコマンドでテスト: node -e "console.log(JSON.parse(process.env.DB_CREDENTIALS))" < .env

3. Node.js バージョンの問題

   • Node.jsのバージョンを確認してください: node -v

   • このサーバーにはNode.js 20以上が必要です

   • 古いバージョンを使用している場合は、Node.js 20 をインストールします: nvm install 20 && nvm use 20

カーソル統合

1. カーソルにサーバーが表示されない

   • .cursor/mcp.jsonファイルが存在し、適切にフォーマットされていることを確認してください。

   • プロジェクト固有の設定を検出するためにカーソルを再起動してください

   • カーソルログでエラーメッセージを確認してください

2. 「クライアントの作成に失敗しました」エラー

   • これは通常、起動中にサーバーがクラッシュしたことを示します

   • エラーを確認するには、詳細なログ出力を使用してサーバーを手動で実行します: node server.js -v

   • カーソル環境でデータベースの資格情報にアクセスできるかどうかを確認します

3. カーソル内にツールがありません

   • サーバーが正常に動作していることを確認する（ログを確認する）

   • MCPツールパネルの更新ボタンをクリックしてみてください

   • カーソルを再起動して再試行してください

PostgreSQL固有の問題

1. 権限拒否エラー

   • データベースユーザーがテーブルに対して適切な権限を持っていることを確認してください

   • 必要な権限を付与してみてください: GRANT SELECT ON ALL TABLES IN SCHEMA public TO username;

2. 「関係が存在しません」エラー

   • テーブルが存在することを確認します: psqlの\dt tablename

   • 正しいデータベースに接続しているかどうかを確認してください

   • ユーザーがテーブルが配置されているスキーマにアクセスできることを確認します。

3. パフォーマンスの問題

   • クエリ結果が大きいと遅延が発生する可能性があるため、LIMIT句の追加を検討してください。

   • データベースに最適化（インデックス、バキューム）が必要かどうかを確認します

さらにヘルプが必要な場合は、詳細なエラー メッセージと操作ログを表示するために、詳細ログ ( -vフラグ) を指定してサーバーを実行できます。

ライセンス

マサチューセッツ工科大学