Model Context Protocol PostgreSQL 服务器

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

功能特性

• 使用连接池连接到 PostgreSQL 数据库
• 实现用于 AI 模型交互的 Model Context Protocol
• 提供数据库模式信息作为资源
• 允许执行带有重试逻辑的 SQL 查询
• 优雅地处理连接错误

前提条件

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

安装

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

npm install

配置

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

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

touch .env

2. 添加以下行，并替换为您的实际数据库凭据：

export DB_CREDENTIALS='{"DB_USER":"your-username","DB_PASSWORD":"your-password","DB_HOST":"your-host","DB_PORT":"5433","DB_NAME":"your-database"}'

回退到 Shell 配置文件

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

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

这在 shell 配置文件未自动加载的环境中尤其有用，例如 Cursor MCP 环境。

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

1. 打开您首选的 shell 配置文件，例如：

nano ~/.zshrc
# 或
nano ~/.bashrc

2. 添加以下行，并替换为您的实际数据库凭据：

export DB_CREDENTIALS='{"DB_USER":"your-username","DB_PASSWORD":"your-password","DB_HOST":"your-host","DB_PORT":"5433","DB_NAME":"your-database"}'

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

自定义凭据变量

您还可以使用自定义环境变量名来代替 DB_CREDENTIALS，方法是在启动服务器时使用 --credentials-var 标志：

node server.js --credentials-var MY_CUSTOM_DB_CREDS

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

组合选项

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

# 使用自定义凭据并启用详细模式
node server.js --credentials-var MY_CUSTOM_DB_CREDS --verbose

# 简写形式也有效
node server.js -c MY_CUSTOM_DB_CREDS -v

用法

启动 MCP 服务器：

# 直接使用 Node.js
node server.js

# 或使用 npm
npm start

日志选项

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

# 启用详细日志
node server.js --verbose

# 或使用 npm
npm start -- --verbose

您也可以使用简写标志 -v：

node server.js -v

服务器将：

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

与 Cursor 集成

此服务器支持 Model Context Protocol (MCP) 并与 Cursor AI 集成。

自动配置

本项目包含一个预配置的 .cursor/mcp.json 文件，用于在 Cursor 中自动设置。

手动配置

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

1. 转到 Cursor 设置 → Features → MCP
2. 单击 "+ Add New MCP Server"
3. 输入以下详细信息：
   • Name: Postgres MCP
   • Type: stdio
   • Command: 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

Cursor 集成

1. 服务器未在 Cursor 中显示

   • 确保 .cursor/mcp.json 文件存在且格式正确
   • 尝试重新启动 Cursor 以检测项目特定的配置
   • 检查 Cursor 日志中是否有任何错误消息

2. "Failed to create client" 错误

   • 这通常表示服务器在启动期间崩溃
   • 使用详细日志记录手动运行服务器以查看错误：node server.js -v
   • 检查数据库凭据是否可在 Cursor 环境中访问

3. Cursor 中没有可用工具

   • 确保服务器运行正常（检查日志）
   • 尝试单击 MCP 工具面板中的刷新按钮
   • 重新启动 Cursor 并重试

PostgreSQL 特定问题

1. 权限被拒绝错误

   • 确保数据库用户对表具有适当的权限
   • 尝试授予所需的权限：GRANT SELECT ON ALL TABLES IN SCHEMA public TO username;

2. "Relation does not exist" 错误

   • 验证该表是否存在：在 psql 中使用 \dt tablename
   • 检查您是否连接到正确的数据库
   • 确保用户有权访问该表所在的模式

3. 性能问题

   • 大型查询结果可能会导致延迟，请考虑添加 LIMIT 子句
   • 检查您的数据库是否需要优化（索引、清理）

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

许可证

MIT