内容
# PostgreSQL MCP 服务器
<p align="center">
<img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python"/>
<img src="https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI"/>
<img src="https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge&logo=postgresql&logoColor=white" alt="PostgreSQL"/>
<img src="https://img.shields.io/badge/Uvicorn-499848?style=for-the-badge&logo=gunicorn&logoColor=white" alt="Uvicorn"/>
<img src="https://img.shields.io/badge/MCP-FF6B6B?style=for-the-badge&logo=protocol&logoColor=white" alt="MCP"/>
</p>
<p align="center">
<strong>适用于 AI 助手通过模型上下文协议的专业 PostgreSQL 数据库访问</strong>
</p>
---
## 功能
**核心能力**
- 完整的模式分析，包括表、列、约束、索引和关系
- 高级的 SQL 查询执行（带 JOIN、CTE、窗口函数和子查询的 SELECT）
- 安全的数据操作（INSERT、UPDATE 具有 ACID 事务安全性）
- 模式管理（表的 CREATE、ALTER、DROP，视图、索引、函数）
- 自动的外键关系映射和约束发现
- 使用 EXPLAIN ANALYZE 进行查询规划和性能优化
- 支持多模式以适应复杂的数据库架构
**安全性和性能**
- 粒度的操作级访问控制
- 具有回滚安全性的 ACID 兼容事务管理
- 多层 SQL 注入防护
- 使用 psycopg3 连接池以获得最佳性能
- 支持行级安全（RLS）
- 全面的验证和错误处理
**受管隐私管道**
- 具有风险评分、成本检查、审批门控和安全查询重写的治理层
- 用于执行前风险预测的 ML 支持的查询风险评分（QRS）分类器
- 数据暴露层，带有 AI 限制的掩码输出和 UI 全数据参考检索
- 具有执行摘要和治理裁决的结构化专业响应
---
## 治理 + 数据暴露流程
```text
用户 -> MCP（AI 推理）
-> 治理层
-> 数据库
-> 数据暴露层（拆分）
-> AI（受限视图）
-> UI（完整数据通过引用）
-> 最终响应
```
### 治理层
- 在执行前评估每个查询
- 将风险分为“低”、“中”、“高”或“关键”并附有数字 QRS 分数（0-100）
- 返回一个操作：`允许`、`重写`、`需要审批`、`阻止`
- 支持高风险操作（如 DELETE/DROP）的密码门控审批
### 数据暴露层
- AI 仅接收掩码、有限结果
- UI 可以通过引用使用 `GET /exposure/{reference_id}` 获取完整结果集
- 完整结果存储在短暂的内存存储中
---
## 安全模型
### 允许的操作
- **读取**：SELECT、WITH（通过 `run_select_psql`）和分析 via `get_query_stats`
- **写入**：INSERT/UPDATE/DELETE/CREATE/ALTER/DROP（通过专用工具）
### 高风险操作
- DELETE 和 DROP 被视为高风险/关键操作由治理
- 需要通过 `governance_password` 进行特殊权限
- `DROP DATABASE` 默认被阻止（`GOV_ALLOW_DROP_DATABASE=false`）
**安全功能**：预备语句、参数化查询、连接隔离、自动回滚、输入净化、只读事务模式支持
---
## 安装
### 要求
- Python 3.8+
- PostgreSQL 12+（包括 AWS RDS、Google Cloud SQL、Azure Database）
- 推荐 512MB RAM
### 快速开始
```bash
# 克隆仓库
git clone https://github.com/your-org/postgres-mcp.git
cd postgres-mcp
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 配置环境
cp .env.example .env
# 使用您的凭证编辑 .env
# 启动服务器
uvicorn server:app --host 127.0.0.1 --port 3333 --reload
```
---
## 配置
创建 `.env` 文件：
```env
# 数据库连接
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=your_database_user
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=your_database_name
# 可选：SSL 配置
POSTGRES_SSLMODE=require
POSTGRES_SSLROOTCERT=/path/to/ca.pem
# 可选：连接池
POSTGRES_POOL_SIZE=10
POSTGRES_POOL_MAX_OVERFLOW=5
POSTGRES_CONNECT_TIMEOUT=10
# 可选：查询限制
MAX_ROWS=1000
QUERY_TIMEOUT=30
# 写入访问控制（默认值：只读）
# 仅当您故意启用 INSERT/UPDATE/ALTER/CREATE 时设置此项。
ALLOW_DB_WRITES=false
# 治理层
GOV_DEFAULT_LIMIT=100
GOV_MAX_ESTIMATED_ROWS=100000
GOV_MAX_ESTIMATED_COST=200000
GOV_REQUIRE_APPROVAL_FOR_WRITES=false
# QRS（ML 查询风险评分）
GOV_APPROVAL_PASSWORD=change_me
GOV_REQUIRE_PASSWORD_FOR_HIGH_RISK=true
GOV_HIGH_RISK_THRESHOLD=70
GOV_CRITICAL_RISK_THRESHOLD=85
GOV_ALLOW_CRITICAL_WITH_PASSWORD=true
GOV_ALLOW_BOOLEAN_OVERRIDE_WITHOUT_PASSWORD=false
GOV_ALLOW_DROP_DATABASE=false
# 数据暴露层
EXPOSURE_AI_MAX_ROWS=100
EXPOSURE_STORE_TTL_SECONDS=900
EXPOSURE_STORE_MAX_ENTRIES=500
# 响应渲染
# markdown（推荐 Copilot Chat）| html（实验性）
RESPONSE_RENDER_MODE=markdown
```
### SSL/TLS 配置
PostgreSQL 支持多种 SSL 模式：
```env
# SSL 模式选项
POSTGRES_SSLMODE=disable # 无 SSL（不推荐）
POSTGRES_SSLMODE=allow # 尝试 SSL，退回到非 SSL
POSTGRES_SSLMODE=prefer # 优先使用 SSL（默认）
POSTGRES_SSLMODE=require # 需要 SSL
POSTGRES_SSLMODE=verify-ca # 需要 SSL + 验证 CA
POSTGRES_SSLMODE=verify-full # 需要 SSL + 验证 CA + 主机名
```
---
## VS Code Copilot 集成
### 要求
- VS Code 1.85+
- GitHub Copilot 扩展且具有有效订阅
- 本地运行 PostgreSQL MCP 服务器
### 通过扩展视图设置（推荐）
1. **打开扩展视图**
- 按 `Ctrl+Shift+X`（Windows/Linux）或 `Cmd+Shift+X`（macOS）
- 或使用命令面板：`扩展：显示扩展`
2. **搜索 MCP 服务器**
- 在搜索字段中输入 `@mcp`
- 浏览 GitHub MCP 注册表中的可用 MCP 服务器
3. **安装自定义 MCP 服务器**
- 如果您的服务器不在注册表中，请单击设置图标（⚙️）
- 从下拉菜单中选择 `添加 MCP 服务器...`
- 选择 **stdio** 作为服务器类型
4. **配置服务器**
```
名称：PostgreSQL 数据库服务器
命令：/path/to/postgres-mcp/.venv/bin/python
参数：["/path/to/postgres-mcp/server.py"]
```
5. **选择安装范围**
- **用户设置**：跨所有工作区可用
- **工作区设置**：仅适用于当前项目（保存到 `.vscode/mcp.json`）
6. **信任服务器**
- VS Code 将提示您信任服务器配置
- 审查服务器详细信息并点击 **信任** 以继续
7. **验证连接**
- 打开 Copilot Chat（`Ctrl+Alt+I` 或 `Cmd+Option+I`）
- 切换到 **代理模式** 使用模式选择器
- 点击 **工具** 图标查看可用的 MCP 工具
- 您应该看到列出的 PostgreSQL 服务器工具
### 通过手动配置设置
在工作区中的 `.vscode/mcp.json` 中添加：
```json
{
"mcpServers": {
"postgresql-database": {
"type": "stdio",
"command": "/absolute/path/to/.venv/bin/python",
"args": ["/absolute/path/to/postgres-mcp/server.py"],
"env": {
"POSTGRES_HOST": "localhost",
"POSTGRES_PORT": "5432",
"POSTGRES_USER": "your_user",
"POSTGRES_PASSWORD": "your_password",
"POSTGRES_DB": "your_database"
}
}
}
}
```
**注意**：使用绝对路径作为命令和参数。`mcp.json` 中的环境变量覆盖 `.env` 文件。
### 使用 MCP 服务器
1. **启用代理模式**
- 打开 Copilot Chat
- 从模式下拉菜单中选择 **代理**
- 代理模式允许 Copilot 使用外部 MCP 工具
2. **查看可用工具**
- 点击聊天界面中的 **工具** 图标
- 切换单个工具的开启/关闭状态
- 可用工具：`list_databases`、`get_schema`、`get_relationships`、`assess_query_risk`、`run_select_psql`、`run_insert_psql`、`run_insert_cte_psql`、`run_update_psql`、`run_delete_psql`、`run_create_psql`、`run_alter_psql`、`run_drop_psql`、`get_query_stats`
3. **在提示中使用**
- 在聊天中输入 `#` 以查看可用工具
- 选择特定工具或让 Copilot 自动选择
- 示例：
- "显示 users 表的数据库模式"
- "评估此查询的风险：在执行前：DELETE FROM users WHERE id = 5"
- "查找上个月的所有订单及其客户名称"
- "分析此查询的性能：SELECT * FROM large_table"
### QRS-First 执行模式
1. **评估查询风险**
- 使用 `assess_query_risk` 和 SQL 查询。
- 审查风险标签、QRS 分数、置信度和审批要求。
2. **仅在审批后执行**
- 对于高风险查询，传递 `governance_password`。
- 替代覆盖：`governance_approved=true`。
示例高风险执行参数：
```json
{
"query": "DELETE FROM users WHERE id = 10",
"database": "app_db",
"governance_password": "change_me"
}
```
4. **管理工具权限**
- 首次使用工具需要明确权限
- 选择以下选项：
- **继续**：仅限此请求运行
- **当前会话**：自动批准当前聊天会话
- **始终允许**：自动批准所有会话（谨慎使用）
### 高级配置
**多数据库设置**（连接多个 PostgreSQL 实例）：
```json
{
"mcpServers": {
"postgres-production": {
"type": "stdio",
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/postgres-mcp/server.py"],
"env": {
"POSTGRES_HOST": "prod.example.com",
"POSTGRES_DB": "production_db"
}
},
"postgres-staging": {
"type": "stdio",
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/postgres-mcp/server.py"],
"env": {
"POSTGRES_HOST": "staging.example.com",
"POSTGRES_DB": "staging_db"
}
}
}
}
```
**工具集**（分组相关工具）：
```json
{
"toolsets": {
"database-read": {
"tools": [
"postgresql-database.get_schema",
"postgresql-database.run_select_psql",
"postgresql-database.get_query_stats"
]
},
"database-write": {
"tools": [
"postgresql-database.run_insert_psql",
"postgresql-database.run_insert_cte_psql",
"postgresql-database.run_update_psql",
"postgresql-database.run_create_psql",
"postgresql-database.run_alter_psql"
]
}
}
}
```
使用规范的 `_psql` 工具名称。
**Copilot 说明**（`.github/copilot-instructions.md`）：
```markdown
查询 PostgreSQL 数据库时：
- 始终使用 get_schema 获取模式
- 使用 run_select_psql 获取 SELECT/WITH 查询
- 使用 run_insert_psql 获取 INSERT 查询
- 使用 run_insert_cte_psql 获取 WITH ... INSERT ... 查询
- 使用 run_update_psql 获取 UPDATE 查询
- 使用 run_create_psql 获取 CREATE 查询
- 使用 run_alter_psql 获取 ALTER 查询
- 利用 PostgreSQL 特性（CTE、窗口函数、JSONB）
- 使用 EXPLAIN ANALYZE 进行查询优化
- 尊重多模式架构（public、auth、analytics 等）
```
### 故障排除
**服务器未出现在工具列表中：
- 验证服务器是否正在运行：`http://127.0.0.1:3333`
- 检查 `mcp.json` 配置语法错误
- 配置更改后重启 VS Code
- 检查输出面板：`视图 > 输出 > MCP 服务器`
**连接错误：
- 验证 PostgreSQL 是否正在运行：`pg_isready -h localhost -p 5432`
- 测试连接：`psql -h localhost -U your_user -d your_database`
- 检查防火墙规则和网络连接
- 验证 `.env` 文件是否具有正确的凭证
**SSL/TLS 错误：
- 确保正确设置了 POSTGRES_SSLMODE
- 验证 SSL 证书是否有效且可访问
- 检查 PostgreSQL 服务器 SSL 配置
- 使用 `POSTGRES_SSLMODE=disable` 进行本地开发（不推荐生产环境）
**权限被拒绝错误：
- 确保 Python 虚拟环境已激活
- 验证文件路径是否绝对而不是相对
- 检查数据库用户是否具有所需权限
- 审查 PostgreSQL `pg_hba.conf` 身份验证设置
**服务器无法启动：
- 查看输出面板：`视图 > 输出 > MCP 服务器`
- 检查 Python 路径：`which python`（macOS/Linux）或 `where python`（Windows）
- 验证所有依赖项：`pip list`
- 检查端口冲突：`lsof -i :3333`（macOS/Linux）
---
## 可用工具
| 工具 | 描述 | 操作 |
|------|-------------|-----------|
| `get_schema` | 获取完整的数据库模式 | 表、列、索引、约束、视图、函数 |
| `get_relationships` | 映射外键关系 | 视觉关系图与基数 |
| `run_select_psql` | 执行读取查询 | SELECT、WITH |
| `run_insert_psql` | 执行 INSERT 查询 | INSERT |
| `run_insert_cte_psql` | 执行 CTE INSERT 查询 | WITH ... INSERT ... |
| `run_update_psql` | 执行 UPDATE 查询 | UPDATE |
| `run_create_psql` | 执行 CREATE 查询 | CREATE |
| `run_alter_psql` | 执行 ALTER 查询 | ALTER |
| `run_create_policy_psql` | 创建行级安全策略 | CREATE POLICY |
| `run_alter_table_rls_psql` | 启用/禁用/强制 RLS 表 | ALTER TABLE ... ROW LEVEL SECURITY |
| `verify_rls_policies` | 验证 RLS 标志和策略 | RLS 检测 |
| `verify_cls_permissions` | 验证列级权限（CLS）| 列权限检测 |
| `get_query_stats` | 查询性能分析 | EXPLAIN 计划和成本估算 |
---
## 使用示例
### 模式探索
```sql
-- 获取完整模式
"Show me all tables and their relationships"
-- 特定模式详细信息
"Describe the users table with all constraints"
-- 多模式支持
"List all tables in the analytics schema"
```
### 数据查询
```sql
-- 基本查询
"Find all active users created in the last 30 days"
-- 复杂连接
"Show customers with their order totals and most recent purchase date"
-- 窗口函数
"Rank products by sales within each category"
-- CTE（公共表表达式）
"Use a CTE to calculate running totals of daily revenue"
```
### 性能分析
```sql
-- 查询规划
"Analyze the execution plan for this query: SELECT * FROM large_table WHERE status = 'active'"
-- 索引建议
"What indexes would improve performance for queries filtering by created_at?"
```
### 数据操作
```sql
-- 插入数据
"Add a new user: email='john@example.com', name='John Doe', role='user'"
-- 批插入
"Insert multiple products from this JSON array"
-- 更新记录
"Update all orders from last month to set status='processed'"
```
### 模式管理```sql
-- 创建表
"Create a products table with id (UUID), name (VARCHAR), price (DECIMAL), created_at (TIMESTAMP)"
-- 添加约束
"Add a foreign key constraint from orders.user_id to users.id"
-- 创建索引
"Create a B-tree index on orders(created_at) for date range queries"
-- 创建视图
"Create a view showing customer order summaries"
```
### 安全策略管理（RLS / CLS）
```sql
-- 构建 RLS 策略
"Create a policy allowing users to read only their own rows"
-- 启用 RLS 位于表级别
"Enable row level security on orders table"
-- 验证 RLS 状态
"Verify RLS is enabled and list all policies for orders table"
-- 验证 CLS 状态
"Show column-level privileges on users table for role app_reader"
```
### PostgreSQL 特性
```sql
--")
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器