内容
# postgres-mcp-server
本地 PostgreSQL MCP 服务器。设计用于 OpenCode 和 MCP 客户端，通过 **stdio** 进行通信。
目标：安全地查询和检查 PostgreSQL 数据库。写入和维护功能默认关闭。
## 快速安全
- 默认 `POSTGRES_ENABLE_WRITE=false`。
- 默认 `POSTGRES_ENABLE_MAINTENANCE=false`。
- 读取查询在 `BEGIN TRANSACTION READ ONLY` 中运行。
- 自省使用参数（ `$1`， `$2`），不拼接用户发送的名称。
- 日志输出到 `stderr`。`stdout` 保留用于 MCP。
- 错误信息不包含密码或带有凭证的完整 URL。
## 安装
```powershell
npm install
npm run build
```
## 配置
主要变量：
| 变量 | 默认值 | 用途 |
|---|---:|---|
| `POSTGRES_URL` 或 `DATABASE_URL` | 必需 | PostgreSQL 连接 URL。 |
| `POSTGRES_ENABLE_WRITE` | `false` | 启用 `INSERT`、`UPDATE`、`DELETE`、`MERGE`、`COPY`。 |
| `POSTGRES_ENABLE_MAINTENANCE` | `false` | 启用 `DROP`、`TRUNCATE`、`ALTER`、`CREATE`、`VACUUM`、`ANALYZE`、`REINDEX`、`GRANT`、`REVOKE`。 |
| `PG_STATEMENT_TIMEOUT_MS` | `30000` | 最大语句超时时间。 |
| `PG_MAX_CONNECTIONS` | `10` | 连接池最大连接数。 |
| `TRANSACTION_TIMEOUT_MS` | `60000` | 待处理事务的最大超时时间。 |
| `MAX_CONCURRENT_TRANSACTIONS` | `5` | 最大并发写事务数。 |
也可以将 URL 作为二进制文件的第一个参数传递。
## OpenCode
安全示例，无真实密钥：
```json
"DB_ejemplo": {
"type": "local",
"command": [
"node",
"D:/work/postgres-mcp-server/dist/index.js"
],
"environment": {
"POSTGRES_URL": "postgresql://USER:PASSWORD@HOST:5432/DB_NAME",
"POSTGRES_ENABLE_WRITE": "false",
"POSTGRES_ENABLE_MAINTENANCE": "false",
"PG_STATEMENT_TIMEOUT_MS": "30000"
},
"enabled": true,
"timeout": 60000
}
```
如果使用已安装的软件包：
```json
"command": ["npx", "-y", "postgres-mcp-server"]
```
## Tools MCP
### `execute_query`
执行读取 SQL：`SELECT`、`WITH`、`EXPLAIN`、`SHOW`。
输入：
```json
{ "sql": "SELECT now()" }
```
### `execute_dml_ddl_dcl_tcl`
仅当 `POSTGRES_ENABLE_WRITE=true` 时执行写入。保持事务打开并返回 `transaction_id`。
输入：
```json
{ "sql": "UPDATE users SET active = true WHERE id = 1" }
```
之后调用 `execute_commit` 或 `execute_rollback`。
### `execute_commit`
确认待处理事务。
```json
{ "transaction_id": "tx_..." }
```
### `execute_rollback`
回滚待处理事务。
```json
{ "transaction_id": "tx_..." }
```
### `execute_maintenance`
仅当 `POSTGRES_ENABLE_MAINTENANCE=true` 时执行维护。
### `list_schemas`
列出用户可见的非内部模式。
### `list_tables`
列出表格。接受可选筛选：
```json
{ "schema_name": "public" }
```
### `describe_table`
描述列、索引和约束。
```json
{ "schema_name": "public", "table_name": "users" }
```
## 开发
```powershell
npm ci
npm run build
npm test -- --run --coverage
npm run lint
```
测试使用模拟数据，不需要真实的 PostgreSQL 数据库。
## CI
GitHub Actions 在 Node 20 和 22 上运行，带有缓存 npm、构建、 lint 和覆盖率检查。行、函数、分支和语句的最低覆盖率为 85%。
## 更多文档
- `docs/configuracion.md`
- `docs/seguridad-sql.md`
- `docs/desarrollo.md`
