read-only-local-postgres-mcp-server

PostgreSQL MCP サーバー

自然言語でのクエリを通じて、Claude Desktop が PostgreSQL データベースを操作できるようにする Model Context Protocol（MCP）サーバーです。

機能

• Claude Desktop または Claude Code から読み取り専用の SQL クエリを実行
• 動的なデータベース接続 - 実行時に任意の PostgreSQL データベースへ接続
• ステートメントの検証と、データベースによって強制される READ ONLY トランザクションによる組み込みのセキュリティ
• Claude Desktop および Claude Code と簡単に連携
• JSON 形式のクエリ結果
• 実行時の上書きに対応した、環境変数ベースのデフォルト設定

クイックスタート

Claude Code ユーザー向け（推奨 - 最も簡単な方法）

claude mcp add postgres -s user -- npx -y @hovecapital/read-only-postgres-mcp-server

次に、データベースの環境変数を設定します。

export DB_HOST=localhost
export DB_PORT=5432
export DB_DATABASE=your_database_name
export DB_USERNAME=your_username
export DB_PASSWORD=your_password

これで完了です！ Claude Code を再起動して、「データベースにどのようなテーブルがありますか？」と尋ねてください。

Claude Desktop ユーザー向け（手動設定）

1. 設定ファイルを開きます：

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

2. 次の設定を追加します：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-postgres-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

3. 保存して Claude Desktop を再起動し、テストします！

前提条件

• Node.js（v16 以上）- mise を使用している場合は、コマンドのパスを適宜更新してください
• PostgreSQL データベースサーバー
• Claude Desktop アプリケーション

インストール

オプション 1：MCP Registry からインストール（推奨）

このサーバーは、Model Context Protocol Registry に capital.hove/read-only-local-postgres-mcp-server として公開されています。

方法 A：Claude Code CLI（最も簡単！）

claude mcp add postgres -s user -- npx -y @hovecapital/read-only-postgres-mcp-server

次に、環境変数を使用してデータベースの認証情報を設定します。Claude Code を再起動すれば完了です！

利点：

• 1 つのコマンドでインストール
• JSON の手動編集は不要
• 自動設定

方法 B：JSON を手動で設定

Claude Desktop の場合：

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-postgres-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Claude Code の場合：

~/.config/claude-code/settings.json（macOS/Linux）または %APPDATA%\claude-code\settings.json（Windows）を編集します。

{
  "mcp": {
    "servers": {
      "postgres": {
        "command": "npx",
        "args": ["-y", "@hovecapital/read-only-postgres-mcp-server"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "5432",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

オプション 2：npm からインストール

npm install -g @hovecapital/read-only-postgres-mcp-server

オプション 3：Claude Code を使用してインストール

Claude Code を使用している場合、この MCP サーバーを簡単にインストールできます。

# Clone the repository
git clone https://github.com/hovecapital/read-only-local-postgres-mcp-server.git
cd read-only-local-postgres-mcp-server

# Install dependencies and build
npm install
npm run build

次に、MCP 設定に追加して Claude Code を設定します。

オプション 4：手動インストール

1. クローンまたはダウンロード

リポジトリをシステム上のディレクトリに保存します。

mkdir ~/mcp-servers/postgres
cd ~/mcp-servers/postgres
git clone https://github.com/hovecapital/read-only-local-postgres-mcp-server.git .

2. 依存関係をインストール

npm install
npm run build

設定

注： オプション 1（npx を使用した MCP Registry 経由）でインストールした場合、設定はすでに完了しています！このセクションは、オプション 2、3、または 4（npm または手動インストール）を選択したユーザー向けです。

Claude Code の設定

手動でインストールした MCP サーバーを Claude Code で使用する場合は、PostgreSQL サーバーを MCP 設定に追加します。

1. Claude Code の設定を開きます（通常、macOS/Linux では ~/.config/claude-code/settings.json、Windows では %APPDATA%\claude-code\settings.json にあります）。

2. PostgreSQL MCP サーバーの設定を追加します。

{
  "mcp": {
    "servers": {
      "postgres": {
        "command": "node",
        "args": ["/absolute/path/to/read-only-local-postgres-mcp-server/dist/index.js"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "5432",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

1. 変更を反映するために Claude Code を再起動します。

Claude Desktop の設定

手動でインストールした MCP サーバーを Claude Desktop で使用する場合は、Claude Desktop の設定ファイルを開きます。

macOS：

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

Windows：

%APPDATA%\Claude\claude_desktop_config.json

PostgreSQL サーバーの設定を追加します。

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/absolute/path/to/read-only-local-postgres-mcp-server/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Node.js に mise を使用する

Node.js のバージョン管理に mise を使用している場合は、設定で Node.js 実行ファイルのフルパスを使用してください。

環境変数

変数	説明	デフォルト
DB_HOST	PostgreSQL サーバーのホスト名	localhost
DB_PORT	PostgreSQL サーバーのポート	5432
DB_DATABASE	データベース名	postgres
DB_USERNAME	PostgreSQL のユーザー名	postgres
DB_PASSWORD	PostgreSQL のパスワード	（空）
DB_SSL	SSL 接続を有効にする	false
DB_ALLOWED_HOSTS	DB_HOST:DB_PORT に加えて、実行時の接続文字列で接続先に指定できる、カンマ区切りの host:port ペア	（空）

ツール

この MCP サーバーは、Claude が PostgreSQL データベースを操作するための 3 つのツールを公開します。

connect

接続文字列を使用して PostgreSQL データベースに接続します。接続は、変更または切断するまで後続のクエリでも維持されます。接続先は DB_HOST:DB_PORT であるか、DB_ALLOWED_HOSTS に登録されている必要があります。

パラメーター：

パラメーター	型	必須	説明
connectionString	文字列	はい	PostgreSQL の接続文字列

接続文字列の形式：

postgres://username:password@host:port/database?sslmode=require
postgresql://username:password@host:port/database

対応している SSL モード：

• sslmode=require - SSL を必須にします（リモート接続に推奨）
• sslmode=verify-full - 証明書を検証して SSL を必須にします
• sslmode パラメーターなし - SSL を使用しません（ローカル接続用）

使用例（自然言語）：

"Connect to postgres://myuser:[email protected]:5432/production"
"Connect to this database: postgres://admin:secret@localhost/analytics"

応答：

{
  "status": "connected",
  "host": "db.example.com",
  "port": 5432,
  "database": "production",
  "user": "myuser",
  "ssl": true
}

---

disconnect

現在の実行時データベースから切断し、デフォルトの環境変数で設定された接続に戻します。

パラメーター： なし

使用例（自然言語）：

"Disconnect from the current database"
"Go back to the default database"

応答：

{
  "status": "disconnected",
  "message": "Reverted to default environment connection",
  "host": "localhost",
  "database": "postgres"
}

---

query

現在接続しているデータベースに対して、読み取り専用の SQL クエリを実行します。1 回のクエリに限り、接続先を任意で上書きできます。

パラメーター：

パラメーター	型	必須	説明
sql	文字列	はい	実行する SQL クエリ（SELECT のみ）
connectionString	文字列	いいえ	このクエリに限り、接続先を上書きします

使用例（自然言語）：

"Show me all tables in the database"
"SELECT * FROM users LIMIT 10"
"Run this query on postgres://other:pass@host/db: SELECT count(*) FROM orders"

応答：

[
  { "id": 1, "name": "Alice", "email": "[email protected]" },
  { "id": 2, "name": "Bob", "email": "[email protected]" }
]

---

LLM 向けツールリファレンス

この MCP サーバーを使用すると、Claude は次の操作を行えます。

1. デフォルトのデータベースにクエリを実行する（環境変数で設定）：

   User: "What tables are in my database?"
   Claude: [Uses query tool with SQL: "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"]
   

2. 別のデータベースに動的に接続する：

   User: "Connect to postgres://user:pass@newhost/newdb and show me the users table"
   Claude: [Uses connect tool first, then query tool]
   

3. 別のデータベースに 1 回限りのクエリを実行する（アクティブな接続は切り替えません）：

   User: "How many records are in the orders table on postgres://user:pass@analytics/warehouse?"
   Claude: [Uses query tool with connectionString parameter]
   

4. デフォルトの接続に戻す：

   User: "Go back to my local database"
   Claude: [Uses disconnect tool]
   

使用方法

1. 設定を更新した後、Claude Desktop/Code を再起動します
2. データベースについて Claude とチャットを開始します

クエリの例

基本的なクエリ（デフォルト／アクティブな接続を使用）：

"Show me all tables in my database"
"What's the structure of the users table?"
"Get the first 10 records from the products table"
"How many orders were placed last month?"
"Show me users with email addresses ending in @gmail.com"

動的接続の例：

"Connect to postgres://analyst:[email protected]:5432/warehouse"
"Now show me all the tables"
"What's the total revenue in the sales table?"
"Disconnect and go back to my local database"

別のデータベースへの 1 回限りのクエリ：

"Run SELECT count(*) FROM users on postgres://admin:[email protected]/app"
"Check the orders table on my staging database: postgres://dev:dev@staging/app"

Claude は、自然言語でのリクエストを適切な SQL クエリに自動的に変換し、データベースに対して実行します。

セキュリティ機能

読み取り専用操作

サーバーは、環境設定接続と実行時の動的接続の両方を含むすべての接続に対して、次の 3 層で読み取り専用アクセスを強制します。

1. データベースによって強制される読み取り専用トランザクション。 すべてのクエリは BEGIN READ ONLY 内で実行され、その後接続が閉じられるため、何もコミットされません。PostgreSQL 自体が、INSERT、UPDATE、DELETE、MERGE、DDL、SELECT INTO、nextval()、ラージオブジェクトへの書き込み、および CTE（WITH x AS (INSERT ...) SELECT ...）や関数本体に隠された書き込みを、文の表記方法にかかわらず拒否します。
2. クエリごとに 1 つのステートメント。 クエリは拡張クエリプロトコルで送信されます。PostgreSQL はこのプロトコルで 1 つのステートメントのみを許可するため、SELECT 1; DROP TABLE ... はサーバーによって拒否されます。
3. 実行前のステートメント検証。 先頭のコメントを取り除いた後、次のステートメントキーワードのいずれかで始まるクエリは拒否されます。

• データ操作 - INSERT、UPDATE、DELETE、TRUNCATE、COPY、MERGE
• スキーマ／DDL - CREATE、ALTER、DROP、COMMENT、RENAME、REASSIGN
• 権限 - GRANT、REVOKE、SECURITY
• セッション／設定 - SET、RESET、DISCARD、LOAD
• プロシージャ／動的実行 - CALL、DO、EXECUTE、PREPARE、DEALLOCATE
• カーソル - DECLARE、FETCH、MOVE、CLOSE
• トランザクション制御 - BEGIN、START、COMMIT、ROLLBACK、SAVEPOINT、RELEASE、LOCK
• メンテナンス - VACUUM、ANALYZE、REINDEX、CLUSTER、REFRESH、CHECKPOINT
• 非同期通知 - NOTIFY、LISTEN、UNLISTEN

読み取り動詞（例：SELECT、WITH、EXPLAIN、SHOW、TABLE、VALUES）で始まるステートメントのみが許可されます。EXPLAIN ANALYZE は対象のステートメントを実行するため、その内部ステートメントも検証されます。

読み取り専用トランザクションでは、サーバーのファイルシステムにアクセスする関数、任意の SQL を実行する関数、またはプロセスの状態を変更する関数を防げません。そのため、クエリのテキスト内のどこかに次のいずれかが含まれる場合も拒否されます：pg_read_file、pg_read_binary_file、pg_stat_file、pg_ls_*、pg_file_*、pg_logdir_ls、pg_logfile_rotate、lo_import、lo_export、dblink*、query_to_xml*、crosstab*、connectby、set_config、pg_terminate_backend、pg_cancel_backend、pg_reload_conf、pg_rotate_logfile、pg_sleep*。これらの名前を別の表記で記述できるため、Unicode エスケープ識別子（U&"..."）も拒否されます。

関数名の照合は拒否リスト方式であり、すべてを網羅することはできません。以下の専用読み取り専用ロールを使うと、ファイル操作に必要な基盤権限（pg_write_server_files、pg_read_server_files、スーパーユーザー権限）が取り除かれるため、推奨される設定です。

動的接続のセキュリティ

connect ツールまたは connectionString パラメーターを使用する場合：

• ホスト許可リスト - 実行時の接続文字列で指定できる接続先は、DB_HOST:DB_PORT または DB_ALLOWED_HOSTS に登録された host:port の組み合わせのみです。その他の接続先はソケットを開く前に拒否されるため、ツールを使用してホストやそのネットワークのポートをスキャンすることはできません。
• 読み取り専用の強制は引き続き適用 - 接続元にかかわらず、すべてのクエリが検証されます
• 認証情報はログに記録されない - パスワードを含む接続文字列がログに書き込まれることはありません
• 応答のサニタイズ - connect ツールの応答にパスワードは含まれません
• セッションベース - 実行時の接続は、現在の MCP セッション中のみ保持されます

推奨データベース設定

セキュリティを強化するには、MCP サーバー専用の読み取り専用ユーザーを作成します：

-- Create a read-only user
CREATE USER claude_readonly WITH PASSWORD 'secure_password';

-- Grant only SELECT permissions on your specific schema
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

-- Grant permissions for future tables (optional)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO claude_readonly;

トラブルシューティング

接続の問題

1. PostgreSQL が起動していることを確認する：PostgreSQL サーバーが稼働中か確認します
2. 認証情報を確認する：ユーザー名とパスワードが正しいことを確認します
3. ネットワーク接続を確認する：Claude Desktop から PostgreSQL サーバーに接続できることを確認します

設定に関する問題

1. 再起動が必要です：設定を変更した後は、必ず Claude Desktop を再起動してください
2. パスの正確性：dist/index.js への絶対パスが正しいことを確認してください
3. JSON 構文：claude_desktop_config.json の形式を検証してください

デバッグモード

サーバーのログを確認するには、サーバーを手動で実行します。

node dist/index.js

ファイル構成

~/mcp-servers/postgres/
├── src/
│   └── index.ts
├── dist/
│   ├── index.js
│   └── index.d.ts
├── package.json
├── tsconfig.json
└── node_modules/

依存関係

• @modelcontextprotocol/sdk：MCP プロトコルの実装
• pg：Node.js 用 PostgreSQL クライアント

コントリビューション

問題や機能改善のリクエストをお気軽にお送りください。

ライセンス

このプロジェクトはオープンソースで、MIT License の下で利用できます。

サポート

問題が発生した場合は、以下をお試しください。

1. 上記のトラブルシューティングのセクションを確認する
2. PostgreSQL への接続を個別に確認する
3. Claude Desktop が最新バージョンに更新されていることを確認する
4. Claude Desktop の MCP ドキュメントを確認する

---

注：このサーバーは開発および分析を目的として設計されています。本番環境で使用する場合は、追加のセキュリティ対策と監視を検討してください。