使用说明

项目简介

postgres-mcp 是一个 MCP (Model Context Protocol) 服务器的示例实现，它使得大型语言模型 (LLM) 能够通过标准化的 MCP 协议与 PostgreSQL 数据库进行交互。该服务器提供了资源 (Resources)、工具 (Tools) 和 Prompt 模板 (Prompts)，允许 LLM 客户端获取数据库的结构信息、执行 SQL 查询等操作。

主要功能点

数据库结构探索：允许 LLM 获取 PostgreSQL 数据库的 schema 和 table 的元数据信息。
表信息查看：提供查看数据库表中字段详细信息的功能。
SQL 查询执行：支持执行 SQL SELECT 查询，并以 YAML 格式返回结果，方便 LLM 理解和处理。
预定义 Prompt 模板：内置多种 Prompt 模板，用于描述 schema 和 table 信息，以及查询数据。

安装步骤

克隆仓库

git clone https://github.com/Tibiritabara/postgres-mcp
cd postgres-mcp

创建并激活虚拟环境

python -m venv .venv
source .venv/bin/activate  # 或 .venv\Scripts\activate (Windows)

安装 UV (可选，推荐)
```
pip install uv
```

安装依赖

uv sync # 如果安装了 uv
# 或
pip install -r requirements.txt # 如果没有安装 uv

配置环境变量
- 复制 '.env.example' 文件并重命名为 '.env'。
- 根据你的 PostgreSQL 数据库配置，修改 '.env' 文件中的环境变量，例如数据库主机、端口、用户名、密码和数据库名。

服务器配置

为了让 MCP 客户端连接到 postgres-mcp 服务器，你需要在客户端的 MCP 配置文件（例如 '.cursor/mcp.json'）中添加如下服务器配置。请根据你的实际安装路径进行调整：

{
  "mcpServers": {
    "postgres-mcp-server": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "src.main"],
      "env": {
        "APP_NAME": "mcp-demo",
        "DB_HOST": "localhost", // PostgreSQL 主机地址
        "DB_PORT": "5432",      // PostgreSQL 端口
        "DB_USER": "postgres",   // PostgreSQL 用户名
        "DB_PASSWORD": "postgres", // PostgreSQL 密码
        "DB_NAME": "postgres"     // PostgreSQL 数据库名
      }
    }
  }
}

配置参数说明:

command: 启动 MCP 服务器的命令。这里指向虚拟环境中的 Python 解释器。
args: 传递给 'command' 的参数，用于执行 'src/main.py' 模块，启动 FastMCP 服务器。
env: 环境变量配置，用于配置 PostgreSQL 数据库连接信息和应用名称。请务必根据你的 PostgreSQL 数据库实际情况修改 'DB_HOST', 'DB_PORT', 'DB_USER', 'DB_PASSWORD', 'DB_NAME' 的值。'/path/to/your/venv/bin/python' 需要替换为你的虚拟环境 python 解释器的实际路径。

基本使用方法

启动 MCP 服务器 在项目根目录下，运行以下命令启动服务器：
```
python -m src.main
```
服务器启动后，会监听 MCP 客户端的请求。

客户端交互 你可以使用 MCP 客户端库（例如 'mcp-client'）与服务器进行交互。以下是一些示例代码，展示如何使用客户端获取资源和调用工具：

from mcp.client import get_client

# 假设服务器运行在本地默认端口
client = get_client("stdio:") # 或 "http://localhost:8000" 如果服务器配置为 HTTP

# 获取 schema 信息
schema_info = client.get_resource("database://public")
print("Schema Info:", schema_info)

# 获取表信息
table_info = client.get_resource("database://public/tables/users")
print("Table Info:", table_info)

# 执行 SQL 查询工具
query_result = client.invoke_tool("query_database", {"query": "SELECT * FROM users LIMIT 5"})
print("Query Result:", query_result)

请确保你的 MCP 客户端已正确配置并连接到运行中的 postgres-mcp 服务器。

关键词