AI导哈

PostgreSQL MCP服务器

一个独立的模型上下文协议（MCP）服务器，为AI代理和聊天应用程序提供PostgreSQL数据库访问。

  • by mohmd21x
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 mohmd21x/Postgres-MCP

使用说明

PostgreSQL MCP 服务器

一个独立的模型上下文协议（MCP）服务器，为人工智能代理和聊天应用程序提供PostgreSQL数据库访问服务。

概述

这个MCP服务器实现了完整的MCP协议（2024-11-05），使得AI代理能够通过标准化工具与PostgreSQL数据库进行交互。它支持SSE（服务器发送事件）和HTTP/JSON-RPC两种传输方式。

特点/特性

  • ✅ 全面支持MCP协议 - 实现了初始化、工具/列表、工具/调用、资源/列表和提示/列表功能
  • ✅ PostgreSQL 集成 - 执行查询，列出表，描述模式
  • ✅ 双运输 - 支持SSE和HTTP传输方式
  • ✅ Docker 准备就绪 - 包含Dockerfile和docker-compose.yml文件
  • ✅ 健康检查 - 内置健康监测功能

可用工具

服务器提供了三种MCP工具：

1. postgres_query

在 PostgreSQL 数据库上执行 SQL 查询。

输入：

{
  "query": "SELECT * FROM employees WHERE department='Engineering'"
}

输出： 查询结果以JSON对象数组的形式呈现

2. postgres_list_tables

列出当前数据库中的所有表。

输入： 无需任何（要求/条件）

输出： 表名数组

3. postgres_describe_table

获取特定表的模式信息。

输入：

{
  "table_name": "employees"
}

输出： 包含列名、类型和约束的表结构

快速入门

先决条件

  • Docker 和 Docker Compose
  • PostgreSQL 数据库（或使用随附的数据库）

1. 启动服务器

docker compose up -d

这启动了两个服务：

  • mcp-postgres-db - PostgreSQL 数据库（端口 5433）
  • postgres-mcp-server - MCP服务器（端口8100）

2. 确认它正在运行

# Check health
curl http://localhost:8100/health

# Expected: {"status":"healthy","database":"connected"}

3. 测试MCP端点

# Test SSE endpoint
curl -H "Accept: text/event-stream" http://localhost:8100/mcp

# Test HTTP endpoint  
curl -X POST http://localhost:8100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

配置

环境变量

编辑 docker-compose.yml 进行配置：

postgres-mcp-server:
  environment:
    # Database connection
    POSTGRES_HOST: mcp-postgres-db
    POSTGRES_PORT: 5432
    POSTGRES_USER: demouser
    POSTGRES_PASSWORD: demo123
    POSTGRES_DB: demodb

数据库连接

服务器使用以下设置（通过环境变量配置）连接到 PostgreSQL：

  • 主持人： mcp-postgres-db (Docker 服务名称) 或您的 PostgreSQL 主机
  • 端口： 5432 （内部用）/ 5433 （外部）
  • 数据库： demodb
  • 用户： demouser
  • 密码： demo123

与AI代理的使用

通过mcp-use Python库进行连接

from mcp_use import MCPClient, MCPAgent
from langchain_openai import ChatOpenAI

# Create MCP client
client = MCPClient.from_dict({
    "mcpServers": {
        "PostgreSQL": {
            "url": "http://postgres-mcp-server:8100/mcp",
            "headers": {}
        }
    }
})

# Create agent
llm = ChatOpenAI(model="gpt-4")
agent = MCPAgent(llm=llm, client=client)

# Use it
result = agent.run("Show me all employees in the Engineering department")

关于大型语言模型（LLM）选择的重要说明

为了获得最佳的工具调用结果，请使用：

  • ✅ OpenAI（开放人工智能研究所） GPT-4，GPT-4o，GPT-4o-mini（优秀）
  • ✅ Ollama：（注：Ollama是一个用于本地运行大型语言模型的工具或框架，具体名称可能因上下文而异，但在此处直接翻译为“Ollama”以保持原名。） llama3.1，llama3.2，mistral（表现良好）
  • ⚠️（警告/注意） 避免： qwen2.5:7b（有限制的工具调用支持）

样本数据

随附的 PostgreSQL 数据库包含示例表：

-- Employees table
CREATE TABLE employees (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100),
  email VARCHAR(100),
  department VARCHAR(50),
  salary DECIMAL(10,2)
);

-- Products table
CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100),
  price DECIMAL(10,2),
  stock INT
);

API 端点

端点 方法 描述
/ GET 服务器信息
/health GET 健康检查
/mcp GET/POST MCP协议端点（SSE/HTTP）

发展

无需 Docker 即可运行

# Install dependencies
pip install fastapi uvicorn psycopg2-binary pydantic

# Set environment variables
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_USER=demouser
export POSTGRES_PASSWORD=demo123
export POSTGRES_DB=demodb

# Run server
python server.py

更改后重建

docker compose down
docker compose build --no-cache
docker compose up -d

故障排除

连接被拒绝

如果遇到连接错误，请确保：

  1. PostgreSQL 正在运行： docker compose ps
  2. 端口8100未被使用： lsof -i :8100
  3. 数据库状态良好： curl http://localhost:8100/health

工具调用不起作用

如果人工智能代理发现了工具但没有调用它们：

  1. 检查你的大型语言模型（LLM）是否支持工具调用
  2. 使用明确提示：“调用 postgres_list_tables 工具”
  3. 考虑切换到OpenAI（gpt-4o-mini）

数据库连接问题

检查数据库日志：

docker compose logs mcp-postgres-db

手动验证连接：

docker exec -it mcp-postgres-db psql -U demouser -d demodb

安全考虑事项

⚠️ 这是一个开发/演示环境。对于生产环境：

  1. 更改默认凭据 在 docker-compose.yml 中
  2. 使用环境变量 或者密钥管理
  3. 实现身份验证 对于MCP端点
  4. 限制SQL查询功能 （防止 DROP、DELETE 等操作）
  5. 使用只读数据库用户 在可能的情况下
  6. 启用SSL/TLS 用于数据库连接

与主应用程序的集成

这台MCP服务器既可以独立使用，也可以与主MCP管理系统集成。

独立使用

独立运行，并可从任何兼容MCP的客户端进行连接。

与MCP管理系统的集成

在你的主应用程序设置中添加：

Name: PostgreSQL MCP Server
Type: HTTP/HTTPS
Category: database
URL: http://postgres-mcp-server:8100/mcp

许可证

麻省理工学院许可证

支持

如遇问题或疑问，请查阅：

  1. 服务器日志： docker compose logs postgres-mcp-server
  2. 数据库日志： docker compose logs mcp-postgres-db
  3. 健康终点： curl http://localhost:8100/health

技术细节

  • 协议： MCP 2024年11月5日
  • 交通： SSE（首选）和HTTP/JSON-RPC
  • 服务器： FastAPI + Uvicorn
  • 数据库驱动程序： psycopg2
  • 容器： Python 3.11-slim（轻量级版本）

倾注爱心打造，服务于Model Context Protocol生态系统

相关 MCP