Model Context Protocol PostgreSQL Server

模型上下文协议 PostgreSQL 服务器

该项目实现了一个连接到 PostgreSQL 数据库的模型上下文协议 (MCP) 服务器。它允许 AI 模型通过标准化协议与数据库进行交互。

特征

• 使用连接池连接到 PostgreSQL 数据库
• 实现用于 AI 模型交互的模型上下文协议
• 提供数据库架构信息作为资源
• 允许使用重试逻辑执行 SQL 查询
• 妥善处理连接错误

先决条件

• Node.js 20 或更高版本
• PostgreSQL 数据库
• 数据库的访问凭据

安装

1. 克隆此存储库
2. 安装依赖项：

配置

服务器从项目根目录中的.env文件读取数据库凭据。您需要将数据库凭据以 JSON 字符串的形式添加到DB_CREDENTIALS环境变量中：

1. 在项目根目录中创建一个.env文件：

2. 使用您的实际数据库凭据添加以下行：

回退到 Shell 配置文件

如果.env文件不存在或未找到 credentials 变量，服务器将按以下顺序自动在 shell 配置文件中查找凭据：

1. ~/.zshrc
2. ~/.bashrc
3. ~/.bash_profile
4. ~/.profile

这在 shell 配置文件无法自动获取的环境中特别有用，例如 Cursor MCP 环境。

要在任何 shell 配置文件中设置凭据：

1. 打开您喜欢的 shell 配置文件，例如：

2. 使用您的实际数据库凭据添加以下行：

当.env文件不可用时，服务器将自动检测并使用这些凭据。

自定义凭证变量

您还可以在启动服务器时使用--credentials-var标志来使用自定义环境变量名称而不是DB_CREDENTIALS ：

在这种情况下，您应该在.env文件中定义MY_CUSTOM_DB_CREDS 。

组合选项

您可以根据需要组合不同的命令行选项：

用法

启动 MCP 服务器：

日志记录选项

默认情况下，服务器以静默模式运行，仅显示错误消息。如果要查看所有日志消息，可以使用 verbose 标志：

您还可以使用短标志-v ：

服务器将：

1. 测试数据库连接
2. 使用 stdio 传输启动 MCP 服务器
3. 处理来自 AI 模型的请求

与 Cursor 集成

该服务器支持模型上下文协议 (MCP) 并与 Cursor AI 集成。

自动配置

该项目包括一个预先配置的.cursor/mcp.json文件，用于在 Cursor 内自动设置。

手动配置

要手动将此服务器添加到 Cursor：

1. 前往光标设置 → 功能 → MCP
2. 点击“+ 添加新的 MCP 服务器”
3. 输入以下详细信息：
   • 名称：Postgres MCP
   • 类型：stdio
   • 命令： node /full/path/to/server.js

有关 MCP 与 Cursor 集成的更多信息，请参阅官方文档。

可用工具

该服务器为AI模型提供以下工具：

• query ：使用重试逻辑执行 SQL 查询

资源

服务器将数据库表作为资源公开，从而允许 AI 模型：

• 列出数据库中的所有表
• 查看每个表的架构信息

错误处理

该服务器包括：

• 连接重试逻辑
• 详细的错误日志记录
• 优雅关机处理

故障排除

连接问题

1. 数据库连接失败
   • 检查 PostgreSQL 是否正在运行： pg_isready -h localhost -p 5433
   • 验证.env文件中的凭据是否正确
   • 确保您的 IP 地址可以访问数据库（检查 pg_hba.conf）
   • 尝试使用psql等其他工具连接来验证凭据
2. 环境变量问题
   • 确保您的.env文件位于项目根目录中
   • 检查DB_CREDENTIALS中的 JSON 结构是否有效
   • 验证 JSON 字符串中没有多余的空格或换行符
   • 使用以下命令进行测试： node -e "console.log(JSON.parse(process.env.DB_CREDENTIALS))" < .env
3. Node.js 版本问题
   • 检查你的 Node.js 版本： node -v
   • 此服务器需要 Node.js 20+
   • 如果使用旧版本，请安装 Node.js 20： nvm install 20 && nvm use 20

光标集成

1. 服务器未显示在光标中
   • 确保.cursor/mcp.json文件存在且格式正确
   • 尝试重新启动 Cursor 来检测项目特定的配置
   • 检查游标日志中是否有任何错误消息
2. “无法创建客户端”错误
   • 这通常表示服务器在启动过程中崩溃
   • 使用详细日志记录手动运行服务器以查看错误： node server.js -v
   • 检查数据库凭据是否可以在 Cursor 环境中访问
3. 光标中没有可用工具
   • 确保服务器正常运行（检查日志）
   • 尝试单击 MCP 工具面板中的刷新按钮
   • 重新启动 Cursor 并重试

PostgreSQL 特定问题

1. 权限被拒绝错误
   • 确保数据库用户对表具有适当的权限
   • 尝试授予所需的权限： GRANT SELECT ON ALL TABLES IN SCHEMA public TO username;
2. “关系不存在”错误
   • 验证表是否存在： \dt tablename在 psql 中
   • 检查您是否连接到正确的数据库
   • 确保用户有权访问表所在的架构
3. 性能问题
   • 查询结果较大可能会造成卡顿，考虑添加 LIMIT 子句
   • 检查您的数据库是否需要优化（索引、清理）

如需更多帮助，您可以使用详细日志记录（ -v标志）运行服务器以查看详细的错误消息和操作日志。

执照

麻省理工学院