Read Only Local Postgres MCP Server

🚀 PostgreSQL MCP Server

Model Context Protocol (MCP)サーバーで、Claude Desktopを通じて自然言語クエリでPostgreSQLデータベースとやり取りできます。

🚀 クイックスタート

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を再起動してテストします！

✨ 主な機能

• Claude DesktopまたはClaude Codeを通じて読み取り専用のSQLクエリを実行します。
• 動的なデータベース接続 - 実行時に任意のPostgreSQLデータベースに接続できます。
• クエリ検証による組み込みセキュリティ（SELECT文のみ許可）。
• Claude DesktopおよびClaude Codeとの簡単な統合。
• JSON形式のクエリ結果。
• 実行時の上書きをサポートする環境ベースのデフォルト設定。

📦 インストール

オプション1: MCPレジストリからインストール（推奨）

このサーバーは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サーバーを簡単にインストールできます。

# リポジトリをクローンします
git clone https://github.com/hovecapital/read-only-local-postgres-mcp-server.git
cd read-only-local-postgres-mcp-server

# 依存関係をインストールしてビルドします
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（MCPレジストリとnpxを使用してインストールした場合）は、すでにすべての設定が完了しています！このセクションは、オプション2、3、または4（npmまたは手動インストール）を選択したユーザー向けです。

Claude Code設定

手動でインストールした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設定

手動でインストールした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を使用する場合

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

環境変数

ツール

このMCPサーバーは、ClaudeがPostgreSQLデータベースとやり取りするための3つのツールを公開しています。

connect

接続文字列を使用して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:mypass@db.example.com: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クエリを実行します。オプションで、単一のクエリの接続を上書きできます。

パラメータ:

使用例（自然言語）:

"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": "alice@example.com" },
  { "id": 2, "name": "Bob", "email": "bob@example.com" }
]

LLM用のツールリファレンス

このMCPサーバーを使用すると、Claudeは以下のことができます。

1. デフォルトのデータベースをクエリする（環境変数を介して構成）:

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

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

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

3. 別のデータベースへのワンオフクエリ（アクティブな接続を切り替えずに）:

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

4. デフォルトの接続に戻る:

   ユーザー: "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:password@analytics.example.com: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"

別のデータベースへのワンオフクエリ:

"Run SELECT count(*) FROM users on postgres://admin:secret@prod.example.com/app"
"Check the orders table on my staging database: postgres://dev:dev@staging/app"

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

セキュリティ機能

読み取り専用操作

サーバーは、すべての接続（環境設定された接続と実行時の動的接続の両方）で読み取り専用アクセスを強制します。以下の操作はブロックされます。

• INSERT - 新しいレコードの追加
• UPDATE - 既存のレコードの変更
• DELETE - レコードの削除
• DROP - テーブル/データベースの削除
• ALTER - テーブル構造の変更
• CREATE - 新しいテーブル/データベースの作成
• TRUNCATE - テーブルからすべてのレコードを削除
• GRANT - 権限の変更
• REVOKE - 権限の削除

動的接続のセキュリティ

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

• 読み取り専用の強制は引き続き適用されます - 接続元に関係なく、すべてのクエリが検証されます。
• 資格情報は記録されません - パスワード付きの接続文字列はログに書き込まれません。
• サニタイズされた応答 - 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ドキュメントを確認します。

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