Postgres Connector MCP

🚀 PostgreSQL MCP Server

PostgreSQL MCP Server 是一個用於查詢 PostgreSQL 數據庫的 MCP（模型上下文協議）服務器。通過與 MCP 兼容的客戶端，你可以執行 SQL 查詢、查看錶細節並管理數據庫連接。

🚀 快速開始

你可以按照以下步驟進行安裝並使用 PostgreSQL MCP Server。

✨ 主要特性

• 數據庫連接：通過身份驗證連接到 PostgreSQL 數據庫。
• SQL 執行：執行經過安全驗證的 SELECT 查詢。
• 連接測試：測試數據庫連接狀態。

📦 安裝指南

Claude Desktop 端安裝步驟

步驟 1：下載 MCP 服務器文件

從本倉庫（根目錄）下載 postgres-connector.mcpb 文件。

步驟 2：安裝 MCP 服務器

1. 打開 Claude Desktop。
2. 導航至 設置 > 功能。
3. 點擊 “安裝擴展” 並選擇 postgres-connector.mcpb 文件。

截圖佔位：安裝 .mcpb 文件

步驟 3：配置數據庫連接

安裝完成後，PostgreSQL 連接器將出現在你的 Claude Desktop 中，帶有默認環境變量，你可以使用數據庫詳細信息進行配置。

截圖佔位：顯示環境變量的數據庫配置界面

步驟 4：測試數據庫連接

發送查詢 “test the database connection”。

📚 詳細文檔

配置所需的數據庫設置

你需要為你的 PostgreSQL 數據庫提供以下信息：

在 Claude Desktop 中安裝擴展後，這些環境變量將自動在擴展設置面板中可供配置。

可用工具

1. 測試 PostgreSQL 連接

工具：test-postgres-connection 此工具用於測試數據庫連接並顯示當前配置（為安全起見，密碼會隱藏）。

示例輸出：

✅ 數據庫連接成功！

配置信息：
{
  "host": "localhost",
  "port": "5432",
  "database": "myapp_production",
  "username": "postgres",
  "password": "***hidden***"
}

連接測試結果：[
  {
    "test": 1
  }
]

2. 獲取所有表

工具：get-all-tables 該工具用於檢索數據庫公共模式中的所有表的列表。

示例輸出：

[
  {
    "table_name": "users"
  },
  {
    "table_name": "orders"
  },
  {
    "table_name": "products"
  },
  {
    "table_name": "categories"
  }
]

3. 執行 SQL 查詢

工具：execute-sql-query 此工具用於在數據庫上執行經過安全驗證的 SELECT 查詢。

輸入：

• sql：要執行的 SQL 查詢（僅支持 SELECT 語句）

示例用法：

SELECT id, name, email FROM users LIMIT 5;

示例輸出：

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
]

安全與保障

SQL 查詢驗證

PostgreSQL MCP 服務器包含以下安全措施：

• 只讀操作：僅允許執行 SELECT 語句。
• 危險關鍵字攔截：自動阻止 DROP、DELETE、TRUNCATE、ALTER、CREATE、INSERT、UPDATE 操作。
• 語句級驗證：對每個 SQL 語句進行單獨驗證。
• 安全錯誤處理：捕獲並安全顯示數據庫錯誤。

最佳實踐是為 postgres 連接器創建一個只讀數據庫用戶。

禁止的操作

出於安全考慮，以下 SQL 操作 不被允許：

• DROP（刪除表/數據庫）
• DELETE（刪除數據）
• TRUNCATE（清空表）
• ALTER（修改結構）
• CREATE（創建新對象）
• INSERT（添加數據）
• UPDATE（修改數據）

故障排除

連接問題

問題：“數據庫連接失敗”

• 檢查：驗證主機、端口、數據庫名稱、用戶名和密碼。
• 檢查：確保你的 PostgreSQL 服務器正在運行且可訪問。
• 檢查：驗證你的數據庫用戶是否具有必要的權限。

問題：“連接超時”

• 檢查：你的數據庫服務器可能位於防火牆後面。
• 檢查：主機地址和端口號是否正確。
• 檢查：與數據庫服務器的網絡連接是否正常。

查詢問題

問題：“檢測到危險操作”

• 原因：你試圖執行非 SELECT 語句。
• 解決方案：出於安全原因，僅允許執行 SELECT 查詢。

問題：“查詢執行失敗”

• 檢查：你的 SQL 語法是否正確。
• 檢查：你引用的表和列是否存在。
• 檢查：你的數據庫用戶是否對錶具有 SELECT 權限。

配置問題

問題：MCP 服務器未出現在 Claude Desktop 客戶端中

• 解決方案：重啟 Claude Desktop。
• 檢查：驗證 .mcpb 文件是否正確安裝。
• 檢查：查看 Claude Desktop 控制檯中是否有任何錯誤消息。

問題：環境變量未顯示

• 解決方案：安裝後重啟 Claude Desktop。
• 檢查：確保擴展在 設置 > 功能 中已啟用。

問題：無法配置數據庫設置

• 解決方案：確保所有必需的環境變量都已填寫。
• 檢查：驗證你的數據庫憑據是否正確。

💻 使用示例

獲取數據庫表

使用 get-all-tables 工具檢索數據庫模式中的所有表。

執行查詢

使用 execute-sql-query 工具執行 SELECT 語句，例如：

SELECT * FROM users LIMIT 10;

🔧 技術細節

系統要求

• PostgreSQL 數據庫（版本 9.0 或更高）
• 能夠訪問你的 PostgreSQL 服務器的網絡

依賴項

• Node.js 運行時
• PostgreSQL 客戶端庫
• MCP（模型上下文協議）框架

項目結構

postgres-connector/
├── src/
│   └── server.ts          # 主 MCP 服務器實現
├── package.json           # Node.js 依賴項
├── manifest.json          # MCP 擴展清單
├── icon.png              # 擴展圖標
└── postgres-connector.mcpb # 編譯後的擴展包

📄 許可證

本項目採用 MIT 許可協議，詳情請參閱 LICENSE 文件。

作者

Marty Markenson

• 郵箱：martyamark@gmail.com
• 領英：Marty Markenson

需要幫助？ 在本倉庫中創建一個 issue 或聯繫 martymarkenson。