AI导哈

PostgreSQL MCP服务器

一个实现模型上下文协议（MCP）的服务器，为AI助手提供与PostgreSQL数据库安全交互的标准化接口。

  • by gharshit
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 gharshit/mcpServer

使用说明

PostgreSQL MCP服务器演示

概述

该项目实现了 模型上下文协议（MCP）服务器 它为AI助手与PostgreSQL数据库交互提供了一个标准化的接口。MCP通过定义良好的工具、资源和提示，在人工智能模型和外部数据源之间实现安全、结构化的通信。

理论基础

核心目标

  1. 数据库可访问性：使AI助手能够安全地查询PostgreSQL数据库，而无需直接访问数据库
  2. 结构化交互：通过MCP协议为数据库操作提供标准化工具
  3. 安全：实现具有严格查询验证的只读操作，以防止数据操纵
  4. 情境感知：为智能查询生成提供数据库模式信息和上下文

架构组件

1.MCP服务器框架

  • FastMCP：提供传输层的轻量级MCP服务器实现（stdio/SSE）
  • 传输层：本地开发（stdio）和网络部署（通过HTTP的SSE）的双重传输支持
  • 登记方式：用于自动注册工具、资源和提示的装饰器

2.配置管理

  • 基于YAML的配置：数据库连接和服务器参数的集中设置
  • 环境变量：运行时配置覆盖功能
  • 验证层：确保数据完整性和类型安全的Pydantic模型

3.数据库抽象

  • 连接池：异步PostgreSQL连接，具有自动生命周期管理功能
  • 查询执行引擎：独立的只读操作，具有全面的错误处理功能
  • 结果序列化：用于MCP协议兼容性的一致数据格式转换

4.组件组织

  • 工具：可执行的数据库操作（模式列表、表检查、查询执行）
  • 资源：提供数据库元数据的静态/上下文数据端点
  • 提示：指导AI查询生成的动态指令模板

实施说明

入口点架构

主应用程序充当传输感知启动器，使用适当的通信协议初始化MCP服务器。它既支持通过标准I/O流进行本地开发，也支持通过HTTP流进行生产部署。

配置系统

外部化设置管理从结构化配置文件加载数据库凭据和服务器参数。该系统提供回退机制和环境变量覆盖，以便在不同环境中灵活部署。

数据库连接层

异步连接管理使用连接池建立安全的PostgreSQL连接。抽象层处理连接生命周期、错误恢复和资源清理，同时保持并发操作的连接隔离。

MCP工具实施

六种专用工具提供全面的数据库交互功能：

  • 健康监测：基本连接验证返回服务器状态
  • 架构发现：枚举用于导航的可用数据库架构
  • 表枚举：使用元数据列出指定架构中的表
  • 架构检查：检索详细的列信息和约束
  • 查询执行：禁止操作筛选的安全SQL执行
  • 性能分析：通过EXPLAIN计划生成查询优化见解

资源管理

上下文数据端点提供静态数据库信息和特定于模式的指导。这些为AI助手提供了有关表关系、数据类型和常见查询模式的领域知识，而不需要直接检查数据库。

提示工程

动态指令模板指导AI助手生成适当的数据库查询。该系统为安全的查询构建提供了结构化的工作流程，强调只读操作和性能考虑。

测试框架

连接验证实用程序使开发人员能够验证数据库连接并探索模式结构。测试模块提供诊断功能，用于排除部署问题和验证配置正确性。

设置

  1. 安装依赖项：
uv sync

  1. 在中配置数据库连接 config.yaml

  2. 安装Cloudflare隧道（用于暴露服务器）：

# macOS
brew install cloudflared

# Or download from: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

运行服务器

地方发展（stdio）

MCP_TRANSPORT=stdio uv run python main.py

通过Cloudflare隧道（SSE）公开

  1. 启动服务器 （默认为SSE传输）：
uv run python main.py

服务器将于启动 http://127.0.0.1:8000 默认情况下。

  1. 在另一个终端中，启动Cloudflare隧道:
cloudflared tunnel --url http://127.0.0.1:8000

Cloudflare将提供公共URL（例如。， https://xxxxx.trycloudflare.com)您可以使用它来访问您的MCP服务器。

环境变量

  • MCP_TRANSPORT：运输类型- sse （默认）或 stdio
  • MCP_HOST：主机地址（默认值： 127.0.0.1)
  • MCP_PORT：端口号（默认值： 8000)

例子：

MCP_PORT=3000 MCP_HOST=0.0.0.0 uv run python main.py

可用工具

  • ping：健康检查
  • list_schemas：列出所有数据库架构
  • list_tables：列出架构中的表
  • get_table_info：获取表架构信息
  • run_sql_query：执行只读SQL查询
  • run_explain_query：获取查询性能指标

资源

  • db://context：数据库上下文信息
  • db://schema/{schema_name}：特定于架构的上下文

提示

  • get_table_data_prompt：提示生成表数据查询

备注

  • 服务器使用 main.py 作为切入点
  • SSE传输用于HTTP/网络访问（Cloudflare隧道）
  • stdio传输用于当地发展

相关 MCP