PostgreSQL CRUD服务

一个提供PostgreSQL数据库CRUD操作和高级查询功能的MCP服务器,允许LLMs通过标准化的MCP工具与数据库交互。

  • by umarmk
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 umarmk/mcp-server

使用说明

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秒

故障排除

常见问题

  1. 连接失败

    • 验证PostgreSQL是否正在运行
    • 检查中的环境变量 .env
    • 确保数据库存在并且用户具有权限
  2. MCP导入错误

    • 安装MCP Python SDK: pip install mcp
    • 确保你使用的是Python 3.10+
  3. 找不到表

    • 运行数据库初始化: python db/init_db.py
    • 验证数据库中是否存在架构

调试模式

通过设置日志级别启用调试日志记录:

import logging
logging.basicConfig(level=logging.DEBUG)

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加新功能的测试
  5. 运行测试套件
  6. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息,请参阅许可证文件。