使用说明
PostgreSQL CRUD MCP服务器
全面 模型上下文协议(MCP) 为PostgreSQL数据库提供CRUD操作和高级查询功能的服务器。该服务器允许像Claude这样的LLM通过标准化的MCP工具与PostgreSQL数据库进行交互。
特性
- 完成CRUD操作:创建、读取、更新、删除记录
- 高级查询:筛选、排序、分页和自定义SQL
- 图式反思:列出表,描述列、约束和索引
- 连接池:高效的数据库连接管理
- 正确的MCP协议:完全符合MCP规范
- 类型安全:全面的类型提示和验证
- 错误处理:强大的错误处理和日志记录
- 测试覆盖率:带pytest的全面测试套件
技术栈
- Python 3.10+
- MCP Python SDK:官方模型上下文协议实施
- asyncpg:高性能PostgreSQL适配器
- python dotenv:环境变量管理
- pytest:支持异步的测试框架
先决条件
- Python 3.10或更高版本
- PostgreSQL数据库(本地或远程)
- 已配置环境变量(请参阅下面的设置)
安装和设置
1.克隆存储库
git clone <repository-url>
cd postgresql-mcp-server
2.创建虚拟环境
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
3.安装依赖项
pip install -r requirements.txt
4.配置环境变量
创建 .env 项目根目录中的文件:
# PostgreSQL Configuration
PG_HOST=localhost
PG_PORT=5432
PG_USER=your_username
PG_PASSWORD=your_password
PG_DATABASE=your_database_name
5.初始化数据库架构
python db/init_db.py
这将创建示例表并插入测试数据以供演示。
用法
运行MCP服务器
# Run the server directly
python postgres_mcp_server.py
# Or test with the comprehensive client
python client_test.py
为Claude Desktop安装
# Install the MCP CLI tool (if not already installed)
pip install mcp
# Install your server for Claude Desktop
mcp install postgres_mcp_server.py --name "PostgreSQL CRUD Server"
安装后,Claude Desktop将自动发现并加载您的数据库工具。
可用工具
MCP服务器提供LLM可以使用的以下工具:
健康与信息
ping:服务器的运行状况检查get_server_info:获取服务器和数据库信息
图式反思
list_tables:列出架构中的所有表describe_table:获取详细的表信息(列、约束、索引)get_table_statistics:获取表统计信息(行数、大小等)
CRUD操作
insert_record:将新记录插入表中select_records:选择具有高级筛选和分页功能的记录update_records:使用WHERE条件更新现有记录delete_records:删除带有WHERE条件的记录(需要安全)
高级查询
execute_custom_query:使用参数执行自定义SQL查询
Claude使用示例
安装后,您可以要求Claude与您的数据库进行交互:
"Show me all tables in the database"
"Create a new user with name 'John Doe' and email 'john@example.com'"
"Find all products in the 'Electronics' category"
"Update the price of product ID 1 to $999.99"
"Get statistics for the users table"
测试
基本服务器测试
# Test that the server can start
python postgres_mcp_server.py --help
# Test database connectivity
python db/init_db.py
测试服务器
# Test basic connectivity
python -c "import asyncio; from postgres_mcp_server import main; print('Server can start')"
项目结构
postgresql-mcp-server/
├── postgres_mcp_server.py # Main MCP server implementation
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
├── README.md # This file
├── SETUP_GUIDE.md # Detailed setup guide
├── LICENSE # MIT License
└── db/
├── connection.py # Database connection utilities
├── schema.sql # Database schema and sample data
└── init_db.py # Database initialization script
安全考虑
- 参数化查询:所有查询都使用参数化语句来防止SQL注入
- WHERE条款必填:UPDATE和DELETE操作需要WHERE子句以确保安全
- 输入验证:全面的输入验证和错误处理
- 连接池:具有超时功能的安全连接管理
- 环境变量:存储在环境变量中的敏感凭据
安全功能
- 必需的WHERE子句:UPDATE和DELETE操作必须包含WHERE条件
- 查询类型验证:自定义查询根据其声明的类型进行验证
- 错误处理:通过信息性消息进行全面的错误处理
- 连接超时:数据库操作具有可配置的超时
- 日志记录:调试和监控的详细日志记录
配置
连接池设置
服务器使用具有以下默认值的连接池:
- 最小连接数: 2
- 最大连接数: 20
- 命令超时:60秒
故障排除
常见问题
-
连接失败
- 验证PostgreSQL是否正在运行
- 检查中的环境变量
.env - 确保数据库存在并且用户具有权限
-
MCP导入错误
- 安装MCP Python SDK:
pip install mcp - 确保你使用的是Python 3.10+
- 安装MCP Python SDK:
-
找不到表
- 运行数据库初始化:
python db/init_db.py - 验证数据库中是否存在架构
- 运行数据库初始化:
调试模式
通过设置日志级别启用调试日志记录:
import logging
logging.basicConfig(level=logging.DEBUG)
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加新功能的测试
- 运行测试套件
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-有关详细信息,请参阅许可证文件。