MCP PostgreSQL 示例

这是一个FastMCP服务器，使大型语言模型（LLMs）能够连接并与PostgreSQL数据库进行交互。该项目演示了如何使用模型上下文协议（MCP）让语言模型查询和探索数据库模式及表。

功能

• 模式探索：获取关于数据库模式的元数据
• 表检查：获取关于表结构的详细信息
• 数据库查询：执行针对数据库的SQL查询
• YAML格式化：结果以YAML格式返回，便于LLMs消费

资源

该服务器公开以下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文件底部取消注释运行函数：

   # if __name__ == "__main__":
   #     print("启动FastMCP服务器...")
   #     mcp.run()
   

2. 启动FastMCP服务器：

   python -m src.main
   

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