AI导哈

PostgreSQL数据库连接服务

一个通过标准化接口提供PostgreSQL数据库连接的MCP服务器，允许AI助手和其他MCP客户端安全高效地与PostgreSQL数据库交互。

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

使用说明

MCP PostgreSQL服务器

一种模型上下文协议（MCP）服务器，通过标准化接口提供PostgreSQL数据库连接。该服务器允许AI助手和其他MCP客户端安全有效地与PostgreSQL数据库交互。

特性

  • 健康检查：监控数据库连接和响应时间
  • 表描述：获取数据库表的详细架构信息
  • SQL查询执行：通过安全控制执行读写操作
  • 连接池：使用asyncpg进行高效的数据库连接管理
  • 安全：内置保护，防止未经授权的架构访问和写入操作
  • JSON解析：对LLM响应中格式错误的JSON进行稳健处理

先决条件

  • Python 3.13或更高版本
  • PostgreSQL数据库
  • MCP客户端（如克劳德桌面等）

安装

  1. 克隆此存储库：
git clone <repository-url>
cd mcp-postgres
  1. 使用uv安装依赖项（推荐）：
uv sync

或者使用pip：

pip install -r requirements.txt

配置

  1. 创建一个 .env 项目根目录中的文件：
PG_DSN=postgresql://username:password@localhost:5432/database_name
  1. 将连接字符串替换为实际的PostgreSQL连接详细信息。

用法

运行服务器

启动MCP服务器（使用uv）：

uv run server.py

或者通过 mcp CLI：

uv run mcp run server.py

您还可以使用MCP检查器进行测试：

npx @modelcontextprotocol/inspector uv run server.py

服务器将启动并通过stdio传输监听MCP客户端连接。

可用工具

1.健康检查(ping)

# Returns connection status and response time
ping()

2.描述表格(describe_table)

# Get table structure information
describe_table({
    "schema": "public",
    "table": "users"
})

# Or as a string
describe_table('{"schema": "public", "table": "users"}')

3.执行查询(query)

# Read operation (default)
query(
    sql="SELECT * FROM users WHERE active = true",
    params={"active": True},
    role="read",
    limit=100
)

# Write operation
query(
    sql="INSERT INTO users (name, email) VALUES ($1, $2)",
    params={"name": "John Doe", "email": "john@example.com"},
    role="write"
)

安全功能

  • 默认情况下为只读：查询默认为只读模式
  • 架构限制：只有 public 架构是可访问的
  • SQL注入保护：使用参数化查询
  • 查询限制：SELECT查询的自动LIMIT子句
  • 基于角色的访问：不同操作的单独读/写角色

支持的SQL操作

读取操作：

  • SELECT 声明
  • SHOW 命令
  • EXPLAIN 查询
  • WITH 条款（CTE）

写入操作：

  • INSERT 声明
  • UPDATE 声明
  • DELETE 声明
  • CREATE 声明
  • DROP 声明
  • ALTER 声明

发展

项目结构

mcp-postgres/
├── server.py          # Main MCP server implementation
├── pyproject.toml    # Project configuration and dependencies
├── README.md         # This file
├── uv.lock           # Dependency lock file
├── .gitignore        # Git ignore rules
└── .env              # Environment variables (create this)

依赖项

  • asyncpg：异步PostgreSQL驱动程序
  • mcp[cli]：模型上下文协议框架
  • psycopg[binary]：PostgreSQL适配器
  • pydantic：数据验证
  • python-dotenv：环境变量管理

添加新工具

要添加新的MCP工具，请使用 @mcp.tool() 装饰师：

@mcp.tool()
async def your_tool_name(param1: str, param2: int) -> Dict[str, Any]:
    """Tool description for the MCP client."""
    # Your implementation here
    return {"result": "success"}

错误处理

该服务器包括强大的错误处理功能，用于：

  • 数据库连接问题
  • SQL语法错误
  • JSON有效载荷格式错误
  • 未经授权的操作
  • 验证错误

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

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

支持

有关问题和疑问，请在项目存储库上打开问题。

相关 MCP