MCP PostgreSQL 演示

一个 FastMCP 服务器，使 LLM 能够连接并与 PostgreSQL 数据库交互。 本项目演示了如何使用模型上下文协议 (MCP) 允许语言模型查询和探索数据库模式和表。

特性

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

资源

服务器公开以下 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  # 在 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 中的 run 函数：

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

2. 启动 FastMCP 服务器：

   python -m src.main
   

3. 服务器将可供 LLM 连接并查询您的 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 ricardo.santos.diaz@gmail.com