内容
# PostgreSQL MCP 服务器
适用于 PostgreSQL 的生产就绪型 **模型上下文协议（MCP）服务器**，使 AI 助手能够安全地与 PostgreSQL 数据库交互。
## 功能
- **30+ MCP 工具** 用于数据库操作
- **安全防护** 配备 SQL 注入检测
- **基于角色的访问控制** （查看者、分析师、开发人员、DBA、管理员）
- **只读模式** 用于安全查询执行
- **事务管理** 配备开始/提交/回滚
- **AI 工具** 用于 SQL 生成、优化和分析
- **结构化审计日志** 用于合规性
- **异步执行** 配备连接池
## 快速开始
### 先决条件
- Python 3.12+
- PostgreSQL 14+
- pip
### 安装
```bash
# 克隆仓库
git clone https://github.com/your-org/postgres-mcp.git
cd postgres-mcp
# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/Mac
# 安装依赖项
pip install -r requirements.txt
# 复制并配置环境
copy .env.example .env
# 编辑 .env 文件以设置数据库凭证
```
### 配置 .env
```env
DATABASE_URL=postgresql+asyncpg://用户:密码@localhost:5432/数据库
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=数据库
DATABASE_USER=数据库用户
DATABASE_PASSWORD=数据库密码
READ_ONLY_MODE=false
ENABLE_AI_SQL=true
ENABLE_AUDIT_LOG=true
```
### 运行服务器
```bash
python -m app.server
```
### 运行测试
```bash
pytest -v
```
## MCP 客户端配置
### Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"postgres": {
"command": "python",
"args": ["-m", "app.server"],
"cwd": "/path/to/postgres-mcp",
"env": {
"DATABASE_URL": "postgresql+asyncpg://用户:密码@localhost:5432/数据库"
}
}
}
}
```
### Cursor / VS Code
```json
{
"mcpServers": {
"postgres": {
"command": "python",
"args": ["-m", "app.server"],
"cwd": "/path/to/postgres-mcp"
}
}
}
```
## 可用工具
### 数据库信息
| 工具 | 描述 |
|------|-------------|
| `list_databases` | 列出所有可访问的数据库 |
| `current_database` | 获取当前数据库名称 |
| `list_schemas` | 列出所有模式 |
| `list_tables` | 列出模式中的表 |
| `list_views` | 列出模式中的视图 |
| `list_functions` | 列出模式中的函数 |
| `list_indexes` | 列出模式中的索引 |
| `list_sequences` | 列出模式中的序列 |
| `list_extensions` | 列出已安装的扩展 |
### 模式检查
| 工具 | 描述 |
|------|-------------|
| `describe_table` | 完整的表描述 |
| `describe_column` | 列元数据 |
| `foreign_keys` | 外键关系 |
| `primary_keys` | 主键列 |
| `unique_constraints` | 唯一约束 |
| `check_constraints` | 检查约束 |
| `table_size` | 表大小（包括索引） |
| `database_size` | 数据库总大小 |
### 查询执行
| 工具 | 描述 |
|------|-------------|
| `execute_select` | 结构化 SELECT 查询 |
| `execute_insert` | 插入行 |
| `execute_update` | 更新行 |
| `execute_delete` | 删除行 |
| `execute_query` | 原始 SQL 执行 |
### 事务
| 工具 | 描述 |
|------|-------------|
| `begin_transaction` | 开始事务 |
| `commit_transaction` | 提交更改 |
| `rollback_transaction` | 撤销更改 |
### 管理工具
| 工具 | 描述 |
|------|-------------|
| `active_connections` | 列出活动连接 |
| `running_queries` | 列出正在运行的查询 |
| `locks` | 列出锁和死锁 |
| `vacuum_status` | 清理和死元组信息 |
| `analyze_table` | 更新表统计信息 |
| `server_version` | 获取服务器版本 |
| `server_settings` | 获取服务器设置 |
### AI 工具
| 工具 | 描述 |
|------|-------------|
| `generate_sql` | 从描述中生成 SQL |
| `explain_sql` | 查询的人性化解释 |
| `optimize_sql` | 查询优化建议 |
| `validate_sql` | 验证而不执行 |
| `detect_sql_injection` | 安全分析 |
| `estimate_query_cost` | 成本估算 |
## 安全
### 防护
服务器自动阻止危险操作：
- `DROP DATABASE` / `DROP ROLE`
- `ALTER SYSTEM`
- `COPY ... PROGRAM`
- `TRUNCATE` （需要确认）
- `pg_sleep()`、`pg_read_file()`、`pg_write_file()`
- 多语句查询
- SQL 注入模式
### 只读模式
当 `READ_ONLY_MODE=true` 时，仅允许 `SELECT` 和 `EXPLAIN`。
### 基于角色的访问
| 角色 | 访问级别 |
|------|-------------|
| 查看者 | 仅读取元数据 |
| 分析师 | SELECT 查询 + AI 工具 |
| 开发人员 | INSERT/UPDATE/DELETE + 事务 |
| DBA | 管理工具（连接、设置） |
| 管理员 | 完全访问权限 |
## Docker
```bash
# 构建
docker build -t postgres-mcp .
# 运行
docker run -p 8000:8000 \
-e DATABASE_URL=postgresql+asyncpg://用户:密码@主机:5432/数据库 \
postgres-mcp
```
## 架构
```
app/
├── server.py # FastMCP 服务器，包含所有工具注册
├── config.py # Pydantic 设置配置
├── database.py # 异步数据库连接管理器
├── guards/
│ ├── sql_guard.py # SQL 验证和风险分类
│ └── permissions.py # 基于角色的访问控制
├── tools/
│ ├── schema_tools.py # 数据库/模式检查
│ ├── query_tools.py # CRUD 查询执行
│ ├── transaction_tools.py # 事务管理
│ ├── admin_tools.py # 监控和管理
│ └── ai_tools.py # AI 驱动的 SQL 分析
├── services/
│ └── audit.py # 审计日志
├── models/
│ └── schemas.py # Pydantic 输入/输出模型
└── utils/
├── logging.py # 结构化日志
└── helpers.py # 实用程序（分页、注入检测）
```
## 开发
```bash
# 安装开发依赖项
pip install -r requirements.txt
# 运行 linter
ruff check app/ tests/
# 运行格式化程序
black app/ tests/
# 运行类型检查器
mypy app/
# 运行测试并生成覆盖率报告
pytest --cov=app --cov-report=term-missing
```
## 未来增强功能
- **pgvector 集成** 用于向量相似性搜索
- **语义搜索** 跨数据库模式
- **RAG 工作流** 用于数据库文档
- **多数据库支持** （MySQL、SQLite、SQL Server）
- **流式传输** 用于大型结果集
- **预备语句缓存**
- **查询结果缓存**，带有 TTL
- **Webhook 通知** 用于模式更改
- **GraphQL 端点**，与 MCP 并存
- **仪表板 UI** 用于监控
## 许可证
MIT
