Read Only Local Postgres MCP Server

🚀 PostgreSQL MCP Server

這是一個模型上下文協議（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註冊表安裝（推薦）

此服務器已發佈在模型上下文協議註冊表中，名稱為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即可完成安裝！ 優點：

• 一鍵安裝。
• 無需手動編輯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（使用npx從MCP註冊表安裝）進行安裝，那麼你已經完成了所有配置！本節適用於選擇選項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"
        }
      }
    }
  }
}

3. 重啟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"
      }
    }
  }
}

使用mise管理Node.js

如果你使用mise進行Node.js版本管理，請確保在配置中使用Node.js可執行文件的完整路徑。

環境變量

💻 使用示例

工具介紹

此MCP服務器提供了三個工具，Claude可以使用這些工具與PostgreSQL數據庫進行交互。

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" }
]

大語言模型工具參考

使用此MCP服務器時，Claude可以：

1. 查詢默認數據庫（通過環境變量配置）：

用戶："What tables are in my database?"
Claude：[使用查詢工具執行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：[先使用連接工具，然後使用查詢工具]

3. 對不同數據庫進行一次性查詢（不切換活動連接）：

用戶："How many records are in the orders table on postgres://user:pass@analytics/warehouse?"
Claude：[使用帶有connectionString參數的查詢工具]

4. 恢復到默認連接：

用戶："Go back to my local database"
Claude：[使用斷開連接工具]

實際使用示例

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 USER claude_readonly WITH PASSWORD 'secure_password';

-- 僅授予特定模式的SELECT權限
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

-- （可選）為未來的表授予權限
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許可證。

💪 支持

如果你遇到問題：

1. 查看上面的故障排除部分。
2. 獨立驗證你的PostgreSQL連接。
3. 確保Claude Desktop已更新到最新版本。
4. 查看Claude Desktop MCP文檔。

注意：此服務器是為開發和分析目的而設計的。對於生產環境使用，請考慮額外的安全措施和監控。