Neon PostgreSQL MCP Server

Neon PostgreSQL MCP サーバー

Neon PostgreSQL データベースへの安全なアクセスを提供する Model Context Protocol（MCP）サーバーです。Claude などの AI アシスタントが、標準化されたツールを通じてデータベースを操作できるようにします。

概要

この MCP サーバーを使用すると、AI アシスタントは次の操作を実行できます。

• SELECT 文を使用してデータをクエリする
• データを変更する（INSERT、UPDATE、DELETE）
• 利用可能なテーブルを一覧表示する
• テーブル構造を確認する

このサーバーは、さまざまなアプローチを示す複数のバージョンを実装しています。

• pg-mcp-server.js - 最新の MCP SDK を使用したモダンな ES モジュール実装
• index.js - クラスベースのアーキテクチャを採用した CommonJS 実装
• basic-pg-server.js - 基本的な MCP プロトコル処理を行うシンプルな実装
• src/index.ts - TypeScript 実装（コンパイルが必要）

機能

• 安全な接続：Neon PostgreSQL への SSL/TLS 暗号化接続
• コネクションプーリング：効率的なデータベース接続管理
• 型安全性：すべての操作に対する入力検証
• エラー処理：わかりやすいメッセージを伴う包括的なエラー処理
• MCP 準拠：Model Context Protocol 仕様の完全な実装

前提条件

• Node.js 18+
• Neon PostgreSQL データベースのアカウントと接続文字列
• MCP 対応のクライアント（例：Claude Desktop、Cursor IDE）

インストール

1. このリポジトリをクローンします。

git clone <repository-url>
cd neon-pg-server

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

npm install

3. 環境変数を使用して Neon PostgreSQL の接続を設定します（以下を参照）。

export NEON_PG_CONNECTION_STRING="postgresql://user:password@host/database?sslmode=require"

環境変数

変数	必須	用途
NEON_PG_CONNECTION_STRING	3つのうちいずれか1つ	単一の接続文字列を、default というプロジェクト名で登録します。従来の単一データベース構成で、引き続き完全にサポートされています。
NEON_PG_CONNECTIONS	3つのうちいずれか1つ	プロジェクト名と接続文字列を対応付ける JSON オブジェクトです。例：{"versemind":"postgresql://...","linecrush":"postgresql://..."}。NEON_PG_CONNECTION_STRING と組み合わせて使用できます。
NEON_PG_CONNECTIONS_FILE	3つのうちいずれか1つ	同じ名前と接続文字列の対応表を含む JSON ファイルへのパスです。1台のマシン上の複数の MCP 登録で接続対応表を共有する場合に便利です（例：~/.secrets/neon-connections.json のように、ファイルをバージョン管理の対象外にしてください）。
NEON_PG_READONLY_PROJECTS	いいえ	execute ツールを完全に拒否するプロジェクト名をカンマ区切りで指定します（読み取りは引き続き可能です）。

最初の3つのうち、少なくとも1つを設定する必要があります。設定値は NEON_PG_CONNECTION_STRING（default として登録）、NEON_PG_CONNECTIONS_FILE、NEON_PG_CONNECTIONS の順に統合されます。後から読み込まれる設定は、名前ごとに前の設定を上書きします（上書き時には警告が stderr に記録されます）。

複数プロジェクトの設定

1つのサーバーインスタンスで複数の Neon プロジェクトに対応できます。プールはプロジェクトごとに初回使用時に遅延作成されるため、6つのプロジェクトを設定しても、起動時に6つのプールが開かれることはありません。

{
  "neon-pg": {
    "command": "node",
    "args": ["/path/to/neon-pg-server/pg-mcp-server.js"],
    "env": {
      "NEON_PG_CONNECTION_STRING": "postgresql://user:[email protected]/verceldb?sslmode=require",
      "NEON_PG_CONNECTIONS": "{\"versemind\":\"postgresql://user:[email protected]/neondb?sslmode=require\",\"linecrush\":\"postgresql://user:[email protected]/verceldb?sslmode=require\"}",
      "NEON_PG_READONLY_PROJECTS": "linecrush"
    }
  }
}

この設定では、次のようになります。

• 引数なしの get_tables は default（従来の接続文字列）に対して実行されます。既存の設定は変更せずに引き続き使用できます。
• project: "versemind" を指定した get_tables は、versemind データベースに対して実行されます。
• project: "linecrush" を指定した execute は、linecrush が NEON_PG_READONLY_PROJECTS に含まれているため拒否されます。
• list_projects には、ホストとデータベースを含む3つすべての名前が表示されます（認証情報は表示されません）。

デフォルトプロジェクトの解決： default という名前のプロジェクト（NEON_PG_CONNECTION_STRING、または NEON_PG_CONNECTIONS 内の default キーから設定）が、読み取りツールのデフォルトになります。default がなく、設定済みのプロジェクトがちょうど1つの場合は、そのプロジェクトがデフォルトになります。名前付きプロジェクトが複数あり、default がない場合、読み取りツールでは project 引数を明示的に指定する必要があります。

複数プロジェクトの安全ルール

これらのルールにより、どのデータベースにアクセスしたかを把握せずにツールの結果を読み取ったり、書き込みを実行したりすることはできません。

1. execute には常に明示的な project 引数が必要です。 書き込みにはデフォルト値も推測による補完もありません。プロジェクトが指定されていない場合、または不明な場合は、使用可能な名前を一覧表示してエラーとなり、何も実行されません。
2. すべてのツール結果には source ブロック（project、database、host）が含まれます。成功・エラー、読み取り・書き込みのいずれの場合も同様です。エラーテキストには [project=... database=...] が先頭に付加されます。
3. NEON_PG_READONLY_PROJECTS は、明示的な project 引数が指定されていても、プロジェクトごとに execute を完全にブロックします。
4. MCP リソース（neon://...）はデフォルトプロジェクトからのみ提供されます。

使用方法

サーバーの実行

使用可能な実装から選択してください。

ES モジュール版（推奨）：

node pg-mcp-server.js

CommonJS 版：

node index.js

基本版：

node basic-pg-server.js

TypeScript 版：

# First compile
npm run build
# Then run
node build/index.js

Claude Desktop との統合

1. Claude Desktop の設定を開きます
2. Developer → MCP Servers に移動します
3. 新しいサーバー設定を追加します。

{
  "neon-postgres": {
    "command": "node",
    "args": ["/path/to/neon-pg-server/pg-mcp-server.js"],
    "env": {
      "NEON_PG_CONNECTION_STRING": "your-connection-string-here"
    }
  }
}

Cursor IDE との統合

1. File → Preferences → Cursor Settings → MCP を開きます
2. Add New Server を選択します
3. サーバースクリプトへのパスを設定します

使用可能なツール

本番環境用の pg-mcp-server.js は 9 個のツールを公開します。各ツールには、Claude／Codex に適したタイトル、読み取り／書き込みの注釈、構造化出力スキーマ、JSON テキストのフォールバックが含まれます。

list_projects 以外のすべてのツールでは、実行対象の名前付き接続を選択する project 引数を任意で指定できます（デフォルト：default プロジェクト）。execute では project 引数が必須です。すべての結果には、実行対象のプロジェクト、データベース、ホストを示す source ブロックが含まれます。

0. プロジェクト一覧ツール

設定済みのプロジェクト接続の名前、ホスト、データベース、デフォルト設定、読み取り専用設定を一覧表示します。認証情報は返しません。

パラメーター： なし

1. クエリツール

読み取り専用の SELECT、WITH、EXPLAIN クエリを実行して、データベースからデータを取得します。

クエリツールは読み取り専用トランザクション内で実行され、上限のないトップレベルの結果セットを安全に 100 行までに制限するため、エージェントは探索時に LIMIT を省略できます。末尾のセミコロンも使用できます。

パラメーター：

• sql（必須）：実行する SQL SELECT、WITH、または EXPLAIN 文
• params（任意）：パラメーター化クエリ用のクエリパラメーターの配列

例：

SELECT * FROM users WHERE age > $1

2. 実行ツール

データを変更する SQL 文（INSERT、UPDATE、DELETE、DDL）を実行します。

パラメーター：

• sql（必須）：実行する SQL 文
• project（必須）：書き込み先の名前付きプロジェクト。書き込みにはデフォルト値は適用されません
• params（任意）：文のパラメーターの配列

NEON_PG_READONLY_PROJECTS に記載されているプロジェクトでは、実行を即座に拒否します。

例：

INSERT INTO users (name, email) VALUES ($1, $2)

3. 遅いクエリの一覧表示ツール

pg_stat_statements が追跡している、実行時間が最も長い文を一覧表示します。

パラメーター：

• limit（任意）：返すクエリの最大数。デフォルトは 10、上限は 25 です
• order_by（任意）：並べ替えに使用する指標。mean_exec_time、total_exec_time、calls、rows のいずれかです
• min_mean_ms（任意）：平均実行時間の最小値（ミリ秒）

pg_stat_statements がインストールされていない場合、わかりにくいデータベースエラーの代わりに、構造化されたセットアップに関する注記を返します。

4. テーブル取得ツール

概算サイズと列数を含めて、public スキーマのテーブルを一覧表示します。

パラメーター： なし

5. スキーマ取得ツール

テーブル名、サイズ、行数の推定値、列数、ページネーションのメタデータを含むスキーマの概要を返します。

パラメーター：

• tables（任意）：含める public テーブルを指定します
• limit（任意）：返すテーブルの最大数。デフォルトは 50、上限は 200 です
• offset（任意）：ページネーションでスキップするテーブル数
• include_all（任意）：バックアップ／アーカイブテーブルを含めます

6. テーブル説明ツール

特定のパブリックテーブルの詳細な構造情報を取得します。

パラメーター：

• table（必須）：説明するテーブルの名前

戻り値：

• 列情報（名前、データ型、NULL 許容、デフォルト値）
• 主キー列、外部キー、インデックス、列挙値、JSONB キー（列ごとに最大 50 件の非 NULL 行からサンプリング）、サイズ、行数の推定値

7. サンプルデータツール

パブリックテーブルの数行と、推定された JSONB 構造を返します。

パラメーター：

• table（必須）：サンプリングするテーブルの名前
• limit（任意）：行数。デフォルトは 3、上限は 10

8. スキーマ検索ツール

大文字と小文字を区別しないテキストパターンで、パブリックテーブル名と列名を検索します。

パラメーター：

• pattern（必須）：テーブル名と列名で検索するテキスト

エージェントの使いやすさ

• サーバー指示により、Claude/Codex にスキーマ検出ツールの使い方を伝え、不要な LIMIT の再試行を避けられます。
• ツールのアノテーションにより、読み取り専用ツールと書き込みツールを区別し、ホストの権限設定と確認をより安全に行えます。
• 補完機能により、テーブル名、プロンプト引数、リソーステンプレート引数、サンプル件数の候補を提示します。
• 構造化ログにより、プロトコルを破損させる出力を stdout に書き込まずに、クライアントがログレベルを制御できます。
• ペイロードの予算管理により、大きすぎるクエリ、サンプル、スロークエリの結果をホストの上限未満に切り詰めてから Claude に渡します。
• スロークエリの検出により、エージェントがクエリのチューニングを始める前に、pg_stat_statements への安全なエントリーポイントを提供します。

セキュリティに関する考慮事項

• 接続文字列：接続文字列は環境変数として保存し、バージョン管理に絶対にコミットしないでください。
• SSL/TLS：サーバーは Neon PostgreSQL への SSL 接続を強制します。
• 接続先の明示：すべてのツールの結果とエラーには、実行対象のプロジェクト、データベース、ホストが記載されるため、結果が別のデータベースのものとして誤って帰属されることはありません。
• 書き込み先の指定：execute には明示的な project 引数が必要で、NEON_PG_READONLY_PROJECTS が適用されます。
• クエリの検証：サーバーは次のことを検証します。
  • Query ツールが受け付けるのは SELECT、WITH、EXPLAIN 文のみです。
  • Query ツールは読み取り専用トランザクション内で実行されます。
  • エージェントが LIMIT を記述しなくても、上位レベルに制限のないクエリ結果は 100 行に制限されます。
  • Execute ツールは SELECT 文を拒否します（代わりに Query ツールを使用してください）。
• ペイロードの制御：クエリとサンプルの結果は、まず大きなセルを切り詰め、最後の手段として行を切り詰めることで、ホストのペイロード上限未満に収められます。
• パラメーター化クエリ：SQL インジェクションを防ぐため、パラメーター化クエリを使用してください。

設定

接続プールの設定

サーバーでは、次のデフォルトのプール設定を使用します。

• 最大接続数：10
• アイドルタイムアウト：30 秒

接続プールの初期化時に、これらの設定を変更できます。

this.pool = new pg.Pool({
  connectionString: CONNECTION_STRING,
  ssl: { rejectUnauthorized: true },
  max: 10,  // Adjust as needed
  idleTimeoutMillis: 30000  // Adjust as needed
});

開発

プロジェクト構成

neon-pg-server/
├── pg-mcp-server.js      # Main ES module implementation
├── index.js              # CommonJS implementation
├── basic-pg-server.js    # Basic implementation
├── src/
│   └── index.ts         # TypeScript implementation
├── build/               # Compiled TypeScript output
├── package.json         # Project dependencies
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file

TypeScript からのビルド

TypeScript 版を使用する場合：

# Install dev dependencies
npm install

# Compile TypeScript
npx tsc

# Run compiled version
node build/index.js

トラブルシューティング

接続の問題

• 接続文字列が正しいことを確認してください。
• Neon データベースがアクティブであることを確認してください。
• SSL が有効になっていることを確認してください（Neon では必須です）。

MCP クライアントの問題

• MCP クライアントがサーバーの実行ファイルを見つけられることを確認してください。
• 環境変数がサーバーに正しく渡されていることを確認してください。
• サーバーログ（stderr に出力）でエラーメッセージを確認してください。

クエリエラー

• SQL 構文が正しいことを確認してください。
• テーブルと列が存在することを確認してください。
• データベース操作に必要な権限があることを確認してください。

貢献

貢献を歓迎します！以下をお願いします。

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 新しい機能のテストを追加します。
4. プルリクエストを送信します。

ライセンス

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

謝辞

• Model Context Protocol SDK を使用して構築されています。
• Neon PostgreSQL を基盤としています。
• MCP エコシステムとコミュニティに着想を得ています。