MCP PostgreSQL Demo

MCP PostgreSQL 演示

一个 FastMCP 服务，可让大模型连接并与 PostgreSQL 数据库交互。本项目展示了如何使用 Model Context Protocol（MCP），让语言模型查询和探索数据库架构与表。

功能

• 架构探索：获取数据库架构的元数据
• 表检查：获取表结构的详细信息
• 数据库查询：对数据库执行 SQL 查询
• YAML 格式：以 YAML 格式返回结果，便于大模型使用

资源

该服务提供以下 MCP 资源：

• database://{schema} - 获取架构中所有表的信息
• database://{schema}/tables/{table} - 获取特定表的详细信息

工具

• query_database - 对数据库执行 SQL 查询（仅支持 SELECT 查询）

提示词

该服务包含以下预定义提示词：

• prompt_schema_description - 请求描述数据库架构
• prompt_table_description - 请求描述特定表
• prompt_query_database - 请求获取特定表的数据

前提条件

• Python 3.12 或更高版本
• PostgreSQL 数据库
• UV 包管理器（推荐）

安装

1. 克隆仓库：

   git clone <repository-url>
   cd mcp-demo
   

2. 创建虚拟环境：

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. 安装 UV（如果尚未安装）：

   pip install uv
   

4. 使用 UV 安装依赖：

   uv sync
   

5. 配置环境变量：

   • 将 .env.example 复制为 .env
   • 根据 PostgreSQL 配置更新相应的值

配置

应用使用环境变量进行配置：

变量	描述	默认值
APP_NAME	应用名称	mcp-demo
DB_HOST	PostgreSQL 主机	localhost
DB_PORT	PostgreSQL 端口	5432
DB_USER	PostgreSQL 用户名	postgres
DB_PASSWORD	PostgreSQL 密码	postgres
DB_NAME	PostgreSQL 数据库名称	postgres

使用方法

1. 首先，在 src/main.py 中取消注释运行函数：删除文件底部以下几行的注释：

   # if __name__ == "__main__":
   #     print("Starting FastMCP server...")
   #     mcp.run()
   

2. 启动 FastMCP 服务：

   python -m src.main
   

3. 大模型即可连接该服务并查询 PostgreSQL 数据库。服务运行后，可将 MCP 加载到客户端应用中进行交互。

客户端配置

要在客户端应用中使用此 MCP，请将以下配置添加到客户端的 MCP 配置文件中（例如 .cursor/mcp.json）：

{
  "mcpServers": {
    "postgres-mcp-server": {
      "command": "/path/to/your/venv/bin/mcp",
      "args": ["run", "/path/to/your/postgres-mcp/src/main.py"],
      "env": {
        "APP_NAME": "mcp-demo",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USER": "postgres",
        "DB_PASSWORD": "postgres",
        "DB_NAME": "postgres"
      }
    }
  }
}

请务必将路径替换为虚拟环境和项目目录的实际路径，并更新环境变量以匹配 PostgreSQL 配置。

开发

使用 UV 安装开发依赖：

uv pip install -e ".[dev]"

包含的开发工具：

• 用于笔记本的 JupyterLab
• 用于类型检查的 Pyright
• 用于代码检查的 Ruff

Docker

使用 Docker 运行应用：

1. 构建 Docker 镜像：

   docker build -t mcp-demo .
   

2. 运行容器：

   docker run --env-file .env.docker -p 8000:8000 mcp-demo
   

使用示例

获取架构信息

from mcp.client import get_client

client = get_client("http://localhost:8000")
schema_info = client.get_resource("database://public")
print(schema_info)

获取表详情

table_info = client.get_resource("database://public/tables/users")
print(table_info)

执行查询

result = client.invoke_tool("query_database", {"query": "SELECT * FROM users LIMIT 10"})
print(result)

许可证

[在此添加许可证信息]

贡献者

• Ricardo Santos [email protected]