PostgreSQL Python MCP服务器
中文文档 |英语
一个基于Python的PostgreSQL MCP服务器，提供安全的数据库操作，内置安全检查和基于AST的SQL解析。
特性
- 🔍 数据库列表：列出PostgreSQL实例中的所有数据库
- 📋 表列表：查看已配置数据库中的所有表
- 🔍 表描述：详细的表结构信息
- 📊 安全查询：执行SQL查询（默认情况下仅限SELECT）
- 🛡️ 安全边界：配置的数据库内有严格的操作限制
- ⚙️ 可配置的：支持通过环境变量启用其他操作
- 📋 JSON输出：针对AI消费优化的结构化JSON响应
- 🌳 基于AST的安全：使用抽象语法树进行高级SQL解析，准确率达到100%
安全特性
默认安全模式
- 只允许
SELECT,SHOW,DESCRIBE,EXPLAIN查询 - 阻止所有
WITH语句，因为它们可以包装写操作 - 阻止危险操作，如
DROP,DELETE,UPDATE,INSERT - 将操作严格限制在配置的数据库范围内
- 使用基于AST的分析防止SQL注入攻击
- 检测嵌套的危险操作和基于UNION的攻击
高级模式（可选）
设置环境变量 PG_ALLOW_DANGEROUS=true 以启用：
- 完整的CRUD操作
- 扩展数据库管理功能
配置
环境变量
| 变量 | 描述 | 必填 |
|---|---|---|
PG_HOST | PostgreSQL主机地址和端口（格式：主机：端口或主机） | 是 |
PG_USER | PostgreSQL用户名 | 是 |
PG_PASSWORD | PostgreSQL密码 | 是 |
PG_DATABASE | 目标数据库名称 | 是 |
PG_ALLOW_DANGEROUS | 允许危险操作（true/false） | 否（默认值：false） |
Claude桌面配置示例
添加到您的Claude Desktop配置文件中：
{
"mcpServers": {
"postgresql": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/hexonal/pg-python-mcp-.git",
"pg-python-mcp"
],
"env": {
"PG_HOST": "your-postgres-host:5432",
"PG_USER": "your-username",
"PG_PASSWORD": "your-password",
"PG_DATABASE": "your-database"
}
}
}
}可用工具
1.列表_数据库
列出PostgreSQL实例中的所有数据库（突出显示当前配置的数据库）。
2.列表表
列出当前配置的数据库中的所有表。
3.描述表
描述指定表的结构，包括列名、类型、空约束和键信息。
参数：
table_name（string）：要描述的表的名称
4.execute_query
执行SQL查询语句并以JSON格式返回结果。
参数：
query（string）：要执行的SQL语句
安全约束：
- 默认模式只允许查询操作（SELECT、SHOW、DESCRIBE、EXPLAIN）
WITH在安全模式下，语句总是被拒绝- 使用AST解析自动检测和阻止危险操作
- 操作仅限于配置的数据库范围
- 检测SQL注入尝试的准确率为100%
JSON输出格式：
{
"status": "success",
"message": "Query executed successfully, returned 2 rows",
"columns": ["id", "name", "email"],
"data": [
{
"id": 1,
"name": "User 1",
"email": "user1@example.com"
},
{
"id": 2,
"name": "User 2",
"email": "user2@example.com"
}
]
}安装和使用
使用uvx（推荐）
# Install from Git
uvx --from git+https://github.com/hexonal/pg-python-mcp-.git pg-python-mcp
# Or for local development
uvx pg-python-mcp手动安装
# Clone repository
git clone https://github.com/hexonal/pg-python-mcp-.git
cd pg-python-mcp
# Install dependencies
pip install -e .
# Run server
python -m pg_mcp使用示例
列出所有数据库
Tool: list_databases列出当前数据库中的表
Tool: list_tables描述表格结构
Tool: describe_table
Parameters: {"table_name": "users"}执行查询
Tool: execute_query
Parameters: {"query": "SELECT * FROM users LIMIT 10"}发展
项目结构
pg-python-mcp/
├── pg_mcp/
│ ├── __init__.py # Main MCP server entry point
│ ├── __main__.py # Run script
│ └── pg_handler.py # PostgreSQL handler with AST security
├── test_ast_security.py # AST security validation tests
├── test_stdio.py # MCP protocol testing
├── pyproject.toml # Project configuration
├── README.md # English documentation
└── README_zh.md # Chinese documentation本地开发
# Clone project
git clone https://github.com/hexonal/pg-python-mcp-.git
cd pg-python-mcp
# Install development dependencies
pip install -e ".[dev]"
# Run security tests
python test_ast_security.py
# Test MCP protocol
python test_stdio.py
# Code formatting
black pg_mcp/
isort pg_mcp/
# Type checking
mypy pg_mcp/技术栈
- FastMCP 2.0：具有基于装饰器的工具注册的现代MCP框架
- asyncpg：异步PostgreSQL数据库操作
- SQL解析：用于安全分析的SQL抽象语法树解析
- Python 3.8+：广泛的兼容性支持
安全实施
基于AST的SQL分析
服务器使用抽象语法树解析来实现SQL安全检查的100%准确率：
def is_query_safe(self, query: str) -> tuple[bool, str]:
"""Check query safety using AST parsing"""
try:
parsed = sqlparse.parse(query)
for statement in parsed:
is_safe, error_msg = self._check_statement_safety(statement)
if not is_safe:
return False, error_msg
return True, ""安全测试结果
- ✅ 安全查询：8/8（100%）
- 🛡️ 被阻止的危险查询：10/10（100%）
- 🎯 总体准确度： 100%
许可证
MIT许可证
安全通告
⚠️ 重要安全指南:
- 所有环境变量都是必需的，没有不安全的默认值
- 确保生产环境中PostgreSQL用户的最低权限
- 定期轮换数据库密码
- 避免在配置中使用管理数据库用户
- 在隔离环境中运行此MCP服务器
- 默认安全模式提供基本保护，但不能取代全面的安全策略
故障排除
常见问题
- 连接失败：检查PostgreSQL服务是否正在运行和网络连接
- 环境变量错误：验证所有必需的环境变量是否已正确设置
- 权限错误：确认PostgreSQL用户有访问指定数据库的权限
- 查询被拒绝：检查查询是否包含禁止的关键字，或考虑启用高级模式
- MCP协议问题：确保您使用的是与FastMCP 2.0兼容的配置
获取帮助
- 检查 中文文档 有关更多详细信息
- 查看测试文件以获取使用示例
- 检查AST安全测试是否支持查询模式