mcpg (Compilotbv)

PostgreSQL MCP服务器

PostgreSQL的模型上下文协议服务器，具有用于远程部署的HTTP/SSE传输。使用Python、FastAPI和Docker为Elestio或任何云平台构建。

特性

• HTTP/SSE传输：通过HTTPS进行远程访问
• API密钥验证：安全访问控制
• 查询执行：使用自然语言执行SELECT查询
• 模式管理：创建、更改和删除表和索引
• 数据操作：插入、更新和删除数据
• 用户管理：创建用户和管理权限
• 数据库维护：VACUUM、备份和连接管理
• 安全：只读模式、连接池和查询超时

快速开始

1.构建Docker镜像

docker build -t postgresql-mcp-server .

2.配置环境

生成API密钥：

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

复制 .env.example 到 .env 并更新：

cp .env.example .env
# Edit .env with your PostgreSQL and API key

3.使用Docker Compose运行

docker-compose up -d

服务器将在 http://localhost:3000

4.配置游标IDE

添加到光标MCP设置：

{
  "mcpServers": {
    "postgresql": {
      "url": "https://your-server.com:3000",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

看 ELESTIO_DEPLOY.md 用于部署指南。

可用工具

查询工具

• execute_query -运行SELECT查询
• execute_explain -获取查询执行计划
• list_databases -列出所有数据库
• list_tables -列出架构中的表
• list_columns -显示列信息
• get_table_info -获取详细的表元数据
• get_database_size -获取数据库和表大小

模式管理（DDL）

• create_table -创建新表
• drop_table -删除表
• alter_table -修改表结构
• create_index -创建索引
• drop_index -删除索引
• get_table_ddl -生成CREATE TABLE语句

数据操作（DML）

• insert_data -插入单行
• bulk_insert -插入多行
• update_data -更新行
• delete_data -删除行

用户管理（DCL）

• list_users -列出数据库用户
• create_user -创建新用户
• grant_permissions -授予特权
• revoke_permissions -撤销特权
• list_permissions -显示用户权限

维护

• vacuum_analyze -运行真空分析
• backup_database -创建pg_dump备份
• restore_database -从备份还原
• kill_connections -终止连接
• get_active_connections -显示活动连接
• test_connection -测试数据库连接

使用示例

在Cursor中配置后，自然地与数据库交互：

"Show me all tables in the database"
"What's the structure of the users table?"
"Find the top 10 customers by order count"
"Create a products table with id, name, and price columns"
"Insert a new user with email test@example.com"
"Show me all database users and their permissions"

配置选项

环境变量：

• POSTGRES_HOST -数据库主机（默认：localhost）
• POSTGRES_PORT -数据库端口（默认值：5432）
• POSTGRES_DB -数据库名称
• POSTGRES_USER -数据库用户
• POSTGRES_PASSWORD -数据库密码
• POSTGRES_READONLY -只读模式（默认值：false）
• POSTGRES_SSLMODE -SSL模式（默认：首选）
• POSTGRES_POOL_MIN -最小连接数（默认值：1）
• POSTGRES_POOL_MAX -最大连接数（默认值：10）
• QUERY_TIMEOUT -查询超时（秒）（默认值：30）

安全最佳实践

1. 使用环境变量 对于凭据，永远不要硬编码
2. 启用只读模式 用于勘探： POSTGRES_READONLY=true
3. 创建专用用户 具有最低限度的所需权限
4. 使用SSL连接 用于生产： POSTGRES_SSLMODE=require
5. 设置查询超时 防止长时间运行的查询
6. 限制连接池 根据您的数据库容量

部署选项

选项1：使用Docker Compose（推荐）

编辑 .env 使用您的PostgreSQL凭据：

docker-compose up -d

选项2：直接运行Docker

docker run -i --rm \
  -e POSTGRES_HOST=your_host \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_DB=your_db \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_PASSWORD=your_password \
  postgresql-mcp-server

项目结构

mcpg/
├── src/postgresql_mcp_server/
│   ├── __init__.py
│   ├── server.py              # Main MCP server
│   ├── db_manager.py           # Connection management
│   ├── query_executor.py       # Query execution
│   ├── schema_manager.py       # DDL operations
│   ├── data_manager.py         # DML operations
│   ├── user_manager.py         # User management
│   └── maintenance_manager.py  # Maintenance tools
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
├── cursor-mcp-config.json
├── CURSOR_SETUP.md
└── README.md

故障排除

连接问题

1. 验证PostgreSQL是否可访问：

   docker run -it --rm postgres:16-alpine psql -h host.docker.internal -U user -d db

1. 检查容器到容器通信的Docker网络设置

1. 查看游标日志中的MCP错误

权限错误

• 验证数据库用户是否具有所需的权限
• 检查PostgreSQL pg_hba.conf以获取访问规则
• 使用 test_connection 诊断工具

Docker问题

• 确保Docker守护进程正在运行
• 检查端口冲突（5432）
• 验证映像是否已构建： docker images | grep postgresql-mcp-server

发展

需求

• Python 3.11+
• PostgreSQL 12+
• Docker 20.10+

本地开发

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
# ... other vars

# Run directly
python -m src.postgresql_mcp_server.server

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请打开问题或PR。

支持

对于问题和疑问：

• 检查 CURSOR_SETUP.md 获取设置帮助
• 审查 故障排除 章节
• 打开GitHub问题

其他文件

• 光标设置指南 -详细的Cursor IDE集成
• MCP协议 -MCP规范
• PostgreSQL文档 -PostgreSQL文档