内容
# @node2flow/postgrest-mcp
[](https://smithery.ai/server/node2flow/postgrest)
[](https://www.npmjs.com/package/@node2flow/postgrest-mcp)
[](https://opensource.org/licenses/MIT)
**PostgREST** 的 MCP 服务器 — 一个独立的 Web 服务器，将 PostgreSQL 数据库转换为 RESTful API。提供 10 种工具用于模式发现、CRUD 操作、筛选、资源嵌入和通过模型上下文协议的 RPC。
## 快速开始
### Claude Desktop / Cursor
将以下内容添加到您的 MCP 配置中：
```json
{
"mcpServers": {
"postgrest": {
"command": "npx",
"args": ["-y", "@node2flow/postgrest-mcp"],
"env": {
"POSTGREST_URL": "http://localhost:3000",
"POSTGREST_TOKEN": "您的 JWT token"
}
}
}
}
```
> **注意：** JWT token 是可选的。如果 PostgREST 配置了匿名角色（`db-anon-role`），则模式和读取操作无需身份验证即可工作。
### HTTP 模式
```bash
POSTGREST_URL=http://localhost:3000 POSTGREST_TOKEN=您的 JWT token npx @node2flow/postgrest-mcp --http
```
MCP 端点：`http://localhost:3000/mcp`
### Cloudflare Worker
可在 `https://postgrest-mcp-community.node2flow.net/mcp` 使用
```
POST https://postgrest-mcp-community.node2flow.net/mcp?POSTGREST_URL=http://您的服务器:3000&POSTGREST_TOKEN=您的 JWT token
```
---
## 工具（10）
### 模式（2）— 无需身份验证（带有匿名角色）
| 工具 | 描述 |
|------|-------------|
| `pg_get_schema` | 获取 OpenAPI 模式 — 列出所有表、视图、函数 |
| `pg_describe_table` | 获取列详细信息、类型、表/视图的约束 |
### 读取（3）— 只读
| 工具 | 描述 |
|------|-------------|
| `pg_list_records` | 查询记录，支持筛选、选择、排序、分页 |
| `pg_count_records` | 统计记录（精确、计划或估计） |
| `pg_call_function` | 通过 RPC 调用 PostgreSQL 函数/过程 |
### 写入（5）— 需要身份验证
| 工具 | 描述 | 风险 |
|------|-------------|------|
| `pg_insert_records` | 插入一个或多个记录 | 安全 |
| `pg_update_records` | 更新匹配筛选条件的记录 | 安全（需要筛选条件） |
| `pg_upsert_records` | 插入或更新冲突 | 安全 |
| `pg_delete_records` | 删除匹配筛选条件的记录 | **破坏性** |
| `pg_replace_record` | 完全替换（PUT）单个记录 | 安全 |
---
## 筛选语法
PostgREST 在查询参数中使用强大的筛选语法：
```
# 比较
age=gt.18 # 大于
status=eq.active # 等于
price=lte.100 # 小于或等于
# 模式匹配
name=ilike.*john* # 不区分大小写的 LIKE
email=like.*@gmail.com # 区分大小写的 LIKE
# 列表和 NULL
id=in.(1,2,3) # IN 列表
deleted_at=is.null # NULL 检查
# 逻辑
or=(age.lt.18,age.gt.65) # OR 条件
not.status=eq.inactive # NOT
# 全文搜索
content=fts.postgresql # 全文搜索
# 数组/JSONB
tags=cs.{tech,api} # 数组包含
```
---
## 资源嵌入（JOIN）
使用 `select` 参数查询相关表：
```
*,orders(*) — 嵌入相关表的所有列
id,name,orders(id,total,status) — 嵌入表的特定列
id,author:user_id(name,email) — 重命名嵌入
```
筛选嵌入资源：
```
select: id,name,orders(*)
filter: orders.status=eq.completed
```
---
## 配置
| 参数 | 必需 | 描述 |
|-----------|----------|-------------|
| `POSTGREST_URL` | 是 | PostgREST 服务器 URL（例如 `http://localhost:3000`） |
| `POSTGREST_TOKEN` | 否 | 用于身份验证请求的 JWT token |
---
## JWT 身份验证
PostgREST 使用 JSON Web Tokens（JWT）进行无状态身份验证。
1. 在 PostgREST 配置中设置 `jwt-secret`
2. 使用适当的 `role` 声明生成 JWT
3. 通过 `POSTGREST_TOKEN` 环境变量传递 token
**JWT 声明：**
- `role` — 数据库角色名称（必需用于 RLS）
- `exp` — token 过期时间（Unix 时间戳）
- 自定义声明可在 SQL 中通过 `current_setting()` 访问
> **提示：** 在 PostgREST 配置中使用 `db-anon-role` 进行公共只读访问，无需 token。
---
## 安全
- **更新和删除需要筛选条件** — 防止意外全表操作
- **使用 `pg_count_records`** 在删除前验证筛选条件匹配
- **使用 `return="representation"`** 查看更改内容
- **使用 `pg_describe_table`** 在插入前检查必填列
---
## 什么是 PostgREST？
[PostgREST](https://postgrest.org) 是一个独立的 Web 服务器：
- 将 PostgreSQL **表** 转换为 CRUD 端点（GET、POST、PATCH、PUT、DELETE）
- 将 **视图** 转换为只读端点
- 将 **函数** 转换为 RPC 端点（`/rpc/function_name`）
- 使用 PostgreSQL **行级安全（RLS）** 进行授权
- 自动生成 **OpenAPI** 规范
---
## 许可证
MIT 许可证 - 请参阅 [LICENSE](LICENSE)
版权（c）2026 [Node2Flow](https://node2flow.net)
## 链接
- [npm 包](https://www.npmjs.com/package/@node2flow/postgrest-mcp)
- [PostgREST 文档](https://postgrest.org/)
- [MCP 协议](https://modelcontextprotocol.io/)
- [Node2Flow](https://node2flow.net)
