easy-pg-mcp

easy-pg-mcp 是一個輕量的 Model Context Protocol (MCP) server，讓 AI 助理可以透過安全、結構化的工具介面查詢與檢視 PostgreSQL 資料庫。

本專案使用 Node.js、TypeScript、官方 MCP SDK，以及 pg / node-postgres。Server 透過 stdio 運作，可由 Claude Desktop、Codex、OpenCode 等 MCP client 啟動。

功能

• 使用 node-postgres 的 PostgreSQL connection pool
• 唯讀查詢工具
• INSERT / UPDATE / DELETE 執行工具，以及可選的進階 schema 修改工具
• 批次執行與 CSV 匯入 / 匯出
• 資料表、view、index、trigger 結構查詢
• EXPLAIN 查詢計畫分析
• 目前使用者與 table grant 查詢
• 可選的 policy hook 與 approval workflow

需求

• Node.js 20 以上
• npm
• 可連線的 PostgreSQL 資料庫

安裝

直接用 npx 啟動：

npx -y easy-pg-mcp

本機開發：

cd easy-pg-mcp
npm install
npm run build

設定

| 變數 | 必填 | 預設值 | 說明 | | --- | --- | --- | --- | | PG_CONNECTION_STRING | 否 | - | PostgreSQL connection string。設定後可省略 host/user/password/database | | PG_HOST | 是* | - | PostgreSQL host | | PG_PORT | 否 | 5432 | PostgreSQL port | | PG_USER | 是* | - | PostgreSQL 使用者 | | PG_PASSWORD | 是* | - | PostgreSQL 密碼 | | PG_DATABASE | 是* | - | 資料庫名稱 | | PG_CONNECTION_LIMIT | 否 | 10 | pool 最大連線數 | | PG_IDLE_TIMEOUT | 否 | 30000 | idle timeout，單位毫秒 | | PG_ENABLE_KEEP_ALIVE | 否 | true | 是否啟用 TCP keep-alive | | PG_KEEP_ALIVE_INITIAL_DELAY | 否 | 0 | keep-alive 初始延遲，單位毫秒 | | PG_SSL | 否 | - | 設為 true 啟用 SSL，或 no-verify 關閉憑證驗證 | | PG_READ_ONLY | 否 | false | 設為 true 時不註冊寫入工具 | | PG_MCP_MODE | 否 | readwrite | 設為 readonly 可停用寫入工具；設為 advanced 可啟用 schema 執行工具 | | PG_MCP_ALLOW_TABLES | 否 | - | table allowlist，例如 users,orders | | PG_MCP_DENY_TABLES | 否 | - | table denylist，例如 payments,secrets | | PG_BATCH_MAX_SIZE | 否 | 100 | pg_batch_execute 每批最大參數組數 | | PG_LOG_PATH | 否 | logs | 批次執行與 CSV 匯入 log 目錄 | | PG_POLICY_HOOK | 否 | - | 外部 policy hook HTTP POST URL | | PG_APPROVAL_TTL_SECONDS | 否 | 300 | pending approval 有效秒數 |

* 若已設定 PG_CONNECTION_STRING，則不必另外設定。

.env 範例：

PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=your_password
PG_DATABASE=your_database

MCP Client 範例

Claude Desktop：

{
  "mcpServers": {
    "easy-pg-mcp": {
      "command": "npx",
      "args": ["-y", "easy-pg-mcp"],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "YOUR USERNAME",
        "PG_PASSWORD": "YOUR PASSWORD",
        "PG_DATABASE": "YOUR DB NAME"
      }
    }
  }
}

Codex config.toml：

[mcp_servers.easy-pg-mcp]
args = ["-y", "easy-pg-mcp"]
command = "npx"
enabled = true

[mcp_servers.easy-pg-mcp.env]
PG_HOST = "localhost"
PG_PORT = "5432"
PG_USER = "YOUR USERNAME"
PG_PASSWORD = "YOUR PASSWORD"
PG_DATABASE = "YOUR DB NAME"

可用工具

如果你不確定某個工具該怎麼用，或操作失敗，請先呼叫 pg_manual。它會回傳內建手冊，包含安全使用規則、placeholder 指引，以及 SQL 組合方式。

| 工具 | 說明 | | --- | --- | | pg_manual | 回傳內建手冊。當你不確定如何使用 PostgreSQL 工具，或需要排查操作錯誤時，請先查這個工具 | | pg_query | 執行唯讀 SQL，例如 SELECT | | pg_execute | 執行資料修改 SQL，例如 INSERT、UPDATE、DELETE | | pg_schema_execute | 執行進階 schema SQL，例如 table、view、index、trigger、function DDL。僅在 PG_MCP_MODE=advanced 時註冊 | | pg_batch_execute | 使用多組參數重複執行同一個資料修改 SQL | | pg_import_csv | 依 CSV header 將 UTF-8 CSV 匯入資料表 | | pg_export_csv | 將資料表匯出成 UTF-8 CSV | | explain_query | 對 SELECT 執行 EXPLAIN | | list_tables | 列出目前 schema 的 base tables | | list_views | 列出目前 schema 的 views | | describe_table | 顯示一個或多個資料表的欄位資訊 | | describe_index | 顯示資料表 indexes | | list_triggers | 列出目前 schema 的 triggers | | get_current_privileges | 顯示目前 PostgreSQL 使用者與 table grants | | pg_run_approved_command | 執行已核准的 pending command，僅在 PG_POLICY_HOOK 設定時註冊 | | pg_list_pending_approvals | 列出 pending approvals，僅在 PG_POLICY_HOOK 設定時註冊 | | pg_cancel_approval | 取消 pending approval，僅在 PG_POLICY_HOOK 設定時註冊 |

當 PG_READ_ONLY=true 或 PG_MCP_MODE=readonly 時，pg_execute、pg_schema_execute、pg_batch_execute、pg_import_csv 不會被註冊。

當 PG_MCP_MODE=advanced 時，會註冊 pg_schema_execute，可執行通過 policy 的單一 statement DDL，用於修改 tables、views、indexes、triggers、functions。

參數語法

node-postgres 使用 $1、$2、$3 這種 positional placeholders。不要使用 MySQL 的 ? placeholder。

pg_execute 範例：

{
  "sql": "UPDATE users SET email = $1 WHERE id = $2",
  "params": ["[email protected]", 123]
}

pg_batch_execute 範例：

{
  "sql": "INSERT INTO users (name, email) VALUES ($1, $2)",
  "paramsList": [
    ["Alice", "[email protected]"],
    ["Bob", "[email protected]"]
  ],
  "transaction": "all"
}

批次執行

pg_batch_execute 會用多組參數重複執行同一個參數化寫入 SQL。transaction 可控制交易範圍：

| 值 | 行為 | | --- | --- | | all | 預設值。所有資料列包在同一個 transaction | | batch | 每個內部分批各自使用一個 transaction | | each | 每組參數各自使用一個 transaction | | none | 不主動開啟 transaction |

每筆執行結果會寫入 PG_LOG_PATH 下帶時間戳的 .log 檔，預設路徑為 logs/。Server 啟動時也會自動清除七天前的舊 log。

SQL Policy

• pg_query 只允許單一 statement 的 SELECT、SHOW、EXPLAIN。
• explain_query 只接受單一 SELECT，並在前方加上 EXPLAIN 執行。
• pg_execute 在 write mode 下只允許單一 statement 的 INSERT、UPDATE、DELETE。
• pg_schema_execute 僅在 PG_MCP_MODE=advanced 時可用，允許單一 statement 的 table、view、index、trigger、function CREATE / ALTER / DROP DDL，以及 TRUNCATE。
• pg_batch_execute 與 pg_import_csv 使用和 pg_execute 相同的寫入規則。
• pg_export_csv 會先檢查 table policy。
• 禁止 multi-statement SQL。
• SELECT ... INTO 與 locking reads 會被唯讀查詢工具拒絕。
• PG_MCP_DENY_TABLES 優先於 PG_MCP_ALLOW_TABLES。
• 若設定 PG_MCP_ALLOW_TABLES，所有偵測到的 table 都必須在 allowlist 內。

Table policy 是根據 SQL parser 的 best-effort 檢查；PostgreSQL grants 仍然是最後的安全邊界。

部分 PostgreSQL DDL 無法永遠透過靜態解析對應回 table，例如 DROP INDEX 或 DROP FUNCTION。在 advanced mode 下若需要更嚴格控管，建議搭配 PostgreSQL grants 與 PG_POLICY_HOOK。

Policy Hook 與 Approval

設定 PG_POLICY_HOOK 後，server 會在內建 policy 檢查通過、但命令實際執行前，將每次工具操作 POST 到外部 hook。Hook 必須回傳以下其中一種結果：

{ "status": "accept" }

{ "status": "reject", "message": "Writes are blocked outside maintenance windows." }

{ "status": "approval_required", "message": "User approval is required before updating users." }

若回傳 approval_required，server 會把待執行命令暫存在記憶體中，並回傳 approvalId。之後 MCP host 可以透過 pg_run_approved_command 搭配該 approvalId 執行命令。Pending approvals 只能使用一次，並會在 PG_APPROVAL_TTL_SECONDS 到期後失效。

開發與測試

npm run build
npm run test

若要執行 PostgreSQL integration tests，建立 .env：

TEST_HOST=localhost
TEST_PORT=5432
TEST_USERNAME=test_user
TEST_PASSWORD=test_password
TEST_DB=test_database

測試會在 TEST_DB 建立並刪除暫時資料表、view、function、trigger。若缺少 TEST_* 變數，integration tests 會自動 skip。

授權

MIT。請見 LICENSE.md。