PostgreSQL服务器模型上下文协议
该项目实现了一个连接到PostgreSQL数据库的模型上下文协议（MCP）服务器。它允许AI模型通过标准化协议与您的数据库进行交互。
特性
- 使用连接池连接到PostgreSQL数据库
- 实现AI模型交互的模型上下文协议
- 将数据库架构信息作为资源提供
- 允许使用重试逻辑执行SQL查询
- 优雅地处理连接错误
先决条件
- Node.js 20或更高版本
- PostgreSQL数据库
- 数据库的访问凭据
安装
- 克隆此存储库
- 安装依赖项：
npm install配置
服务器从读取数据库凭据 .env 项目根目录中的文件。您需要将数据库凭据作为JSON字符串添加到 DB_CREDENTIALS 环境变量：
- 创建一个
.env项目根目录中的文件：
touch .env- 使用您的实际数据库凭据添加以下行：
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配置文件中查找凭据：
~/.zshrc~/.bashrc~/.bash_profile~/.profile
这在没有自动获取shell配置文件的环境中特别有用，例如Cursor MCP环境。
要在任何shell配置文件中设置凭据，请执行以下操作：
- 打开您喜欢的shell配置文件，例如：
nano ~/.zshrc
# or
nano ~/.bashrc- 使用您的实际数据库凭据添加以下行：
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在这种情况下，您将定义 MY_CUSTOM_DB_CREDS 在你的 .env 文件代替。
组合选项
您可以根据需要组合不同的命令行选项：
# Use custom credentials and enable verbose mode
node server.js --credentials-var MY_CUSTOM_DB_CREDS --verbose
# Short form also works
node server.js -c MY_CUSTOM_DB_CREDS -v用法
启动MCP服务器：
# Directly with Node.js
node server.js
# Or with npm
npm start记录选项
默认情况下，服务器以静默模式运行，仅显示错误消息。如果要查看所有日志消息，可以使用verbose标志：
# With verbose logging
node server.js --verbose
# Or with npm
npm start -- --verbose您还可以使用短标志 -v:
node server.js -v服务器将：
- 测试数据库连接
- 使用stdio传输启动MCP服务器
- 处理来自AI模型的请求
与Cursor集成
该服务器支持模型上下文协议（MCP），并与Cursor AI集成。
自动配置
此项目包括一个预配置的 .cursor/mcp.json 用于在Cursor中自动设置的文件。
手动配置
要手动将此服务器添加到Cursor，请执行以下操作：
- 转到光标设置→ 特性→ MCP
- 点击“+添加新MCP服务器”
- 输入以下详细信息：
- 名字：Postgres MCP - 类型：stdio - 命令: node /full/path/to/server.js
有关MCP与Cursor集成的更多信息，请参阅 官方文件.
可用工具
服务器为AI模型提供以下工具：
query：使用重试逻辑执行SQL查询
资源
服务器将数据库表作为资源公开，允许AI模型：
- 列出数据库中的所有表
- 查看每个表的架构信息
错误处理
服务器包括：
- 连接重试逻辑
- 详细的错误记录
- 优雅的停机处理
故障排除
连接问题
- 数据库连接失败
- 检查PostgreSQL是否正在运行： pg_isready -h localhost -p 5433 - 在中验证您的凭据 .env 文件正确 - 确保您的IP地址可以访问数据库（检查pg_hba.conf） - 尝试使用其他工具进行连接，例如 psql 验证凭据
- 环境变量问题
- 确保你的 .env 文件位于项目根目录中 - 检查中的JSON结构 DB_CREDENTIALS 有效 - 验证JSON字符串中没有多余的空格或换行符 - 测试： node -e "console.log(JSON.parse(process.env.DB_CREDENTIALS))" < .env
- Node.js版本问题
- 检查你的Node.js版本： node -v - 此服务器需要Node.js 20+ - 如果使用旧版本，请安装Node.js 20： nvm install 20 && nvm use 20
光标集成
- 服务器未显示在光标中
- 确保 .cursor/mcp.json 文件存在并且格式正确 - 尝试重新启动Cursor以检测项目特定的配置 - 检查游标日志是否有任何错误消息
- “创建客户端失败”错误
- 这通常表示服务器在启动过程中崩溃 - 使用详细日志记录手动运行服务器以查看错误： node server.js -v - 检查数据库凭据在Cursor环境中是否可访问
- 游标中没有可用的工具
- 确保服务器正常运行（检查日志） - 尝试单击MCP工具面板中的刷新按钮 - 重新启动Cursor并重试
PostgreSQL特定问题
- 权限被拒绝错误
- 确保数据库用户对表具有适当的权限 - 尝试授予所需权限： GRANT SELECT ON ALL TABLES IN SCHEMA public TO username;
- “关系不存在”错误
- 验证该表是否存在： \dt tablename 在psql中 - 检查您是否连接到正确的数据库 - 确保用户可以访问表所在的架构
- 性能问题
- 较大的查询结果可能会导致延迟，请考虑添加LIMIT子句 - 检查您的数据库是否需要优化（索引、抽真空）
如需更多帮助，您可以使用详细日志记录运行服务器(-v 标志）查看详细的错误消息和操作日志。
许可证
麻省理工学院