postgresql_mcp

Name: postgresql_mcp
Author: JaviMaligno

作者：JaviMaligno2 星标更新：2025-08-07

安装使用来源：spider==github.com

项目介绍

PostgreSQL MCP 服务器

这是一个用于PostgreSQL的模型上下文协议（MCP）服务器，提供数据库查询、模式探索和表管理工具。

功能

查询：执行针对PostgreSQL数据库的SQL查询
列出模式：列出数据库中所有可用的模式
列出表：列出特定模式中的所有表
描述表：获取关于表结构、列、约束和关系的详细信息

安装

先决条件

Python 3.10+
Poetry
PostgreSQL数据库（可以在Docker中运行）

设置

克隆仓库：

git clone <repository-url>
cd postgres_mcp

使用Poetry安装依赖项：

poetry install

设置环境变量：

cp .env.example .env
# 编辑.env文件以包含您的数据库连接详情

配置

服务器使用环境变量进行数据库连接：

POSTGRES_HOST=your_host
POSTGRES_PORT=your_port
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password
POSTGRES_DB=your_db

使用方法

本地运行

# 安装依赖项
poetry install

# 运行MCP服务器
poetry run postgres-mcp

与Cursor IDE配置

要将此MCP服务器与Cursor IDE一起使用：

在项目目录中安装MCP服务器：
```
poetry install
```
找到Poetry虚拟环境路径：
```
poetry env info
```
查找“可执行”路径，类似于： /Users/your-username/Library/Caches/pypoetry/virtualenvs/postgres-mcp-XXXXXX-py3.12/bin/python

配置Cursor MCP设置：打开Cursor设置，并在您的MCP配置中添加以下内容（通常位于~/.cursor/mcp.json）：

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "/Users/your-username/Library/Caches/pypoetry/virtualenvs/postgres-mcp-XXXXXX-py3.12/bin/python",
      "args": ["-m", "postgres_mcp.server"],
      "env": {
        "POSTGRES_HOST": "your_host",
        "POSTGRES_PORT": "your_port",
        "POSTGRES_USER": "your_user",
        "POSTGRES_PASSWORD": "your_passowrd",
        "POSTGRES_DB": "your_database_name",
        "PYTHONPATH": "/path/to/your/postgres_m_ cp/project"
      }
    }
  }
}

更新配置，用您具体的路径和数据库详情替换：
- 将command路径替换为您实际的Poetry虚拟环境Python可执行文件路径
- 更新PYTHONPATH为您的项目目录路径
- 在env部分设置您的数据库连接详情
重启Cursor以加载新的MCP服务器配置。
验证工具是否可用在Cursor的MCP面板中。您应该看到四个工具：
- query - 执行SQL查询
- list_schemas - 列出数据库模式
- list_tables - 列出模式中的表
- describe_table - 获取表结构详情

示例工作配置：

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "/Users/javieraguilarmartin1/Library/Caches/pypoetry/virtualenvs/postgres-mcp-1M6poMko-py3.12/bin/python",
      "args": ["-m", "postgres_mcp.server"],
      "env": {
        "POSTGRES_HOST": "your_host",
        "POSTGRES_PORT": "your_port",
        "POSTGRES_USER": "your_user",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_DB": "your_db",
        "PYTHONPATH": "/paht/to/postgres_mcp"
      }
    }
  }
}

使用Docker运行

构建并运行Docker容器：

# 构建镜像
docker build -t postgres-mcp .

# 运行容器
docker run -it --env-file .env postgres-mcp

使用Docker Compose运行

包括PostgreSQL在内的完整设置：

# 启动PostgreSQL和MCP服务器
docker-compose up

# 在分离模式下运行
docker-compose up -d

# 停止服务
docker-compose down

可用工具

1. 查询工具

对数据库执行SQL查询。

参数：

sql（必需）：要执行的SQL查询

示例：

{
  "name": "query",
  "arguments": {
    "sql": "SELECT * FROM users LIMIT 10"
  }
}

2. 列出模式工具

列出数据库中的所有模式。

参数： 无

示例：

{
  "name": "list_schemas",
  "arguments": {}
}

3. 列出表工具

列出特定模式中的所有表。

参数：

schema（可选）：模式名称（默认："public"）

示例：

{
  "name": "list_tables",
  "arguments": {
    "schema": "public"
  }
}

4. 描述表工具

获取关于表结构的详细信息。

参数：

table_name（必需）：要描述的表名称
schema（可选）：模式名称（默认："public"）

示例：

{
  "name": "describe_table",
  "arguments": {
    "table_name": "users",
    "schema": "public"
  }
}

开发

运行测试

诊断工具（用于设置验证和故障排除）：

python test_connectivity.py

全面的连通性检查，带有用户友好的输出和故障排除指导。

单元测试（用于开发和CI/CD）：

poetry run pytest

自动测试套件，用于开发工作流程和代码质量保证。

代码格式化

# 格式化代码
poetry run black .

# 检查代码风格
poetry run flake8 .

# 类型检查
poetry run mypy .

架构

MCP服务器使用以下组件构建：

MCP SDK：用于实现模型上下文协议
psycopg2：用于PostgreSQL数据库连接
asyncio：用于异步操作
Poetry：用于依赖管理

贡献

分叉仓库
创建功能分支
进行更改
添加测试
提交拉取请求

许可证

本项目根据MIT许可证发布 - 请参阅LICENSE文件了解详细信息。

故障排除

数据库连接问题

确保PostgreSQL正在运行且可访问
检查您的环境变量
如果使用Docker，请验证网络连接

MCP服务器问题

检查日志以获取详细的错误消息
确保已安装所有依赖项
验证Python版本兼容性

支持

对于问题和疑问，请在GitHub存储库中打开一个Issue。