PostgreSQL SSH MCP服务器
一个内置SSH隧道的安全PostgreSQL MCP服务器。通过堡垒主机自动连接到数据库——无需手动 ssh -L 必修的。
特性
- 双重运输 --STDIO用于克劳德桌面，可流式HTTP用于ChatGPT
- SSH隧道 --内置隧道，带自动重新连接和TOFU（首次使用时信任）
- 默认情况下为只读 --安全生产；显式启用写入
- OAuth支持 --用于安全ChatGPT连接的Auth0集成
- 连接池 --具有可配置限制的高效资源管理
______________________________________________________________________
建筑
______________________________________________________________________
快速开始
克劳德桌面（STDIO）
添加到您的Claude Desktop配置中：
| 平台 | 配置位置 |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| 窗户 | %APPDATA%/Claude/claude_desktop_config.json |
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@zlash65/postgresql-ssh-mcp"],
"env": {
"DATABASE_URI": "postgresql://user:password@localhost:5432/mydb"
}
}
}
}ChatGPT（流式HTTP）
DATABASE_URI="postgresql://user:pass@localhost:5432/mydb" npx @zlash65/postgresql-ssh-mcp-http然后配置ChatGPT以连接到 https://your-subdomain.example.com/mcp.
注： ChatGPT需要HTTPS。使用隧道（ngrok、Cloudflare隧道）进行本地测试。
______________________________________________________________________
可用工具
查询工具
| 工具 | 说明 |
|---|---|
execute_query | 使用参数化查询执行SQL。结果上限为 MAX_ROWS. |
explain_query | 获取文本、JSON、YAML或XML格式的EXPLAIN计划。支持分析。 |
架构工具
| 工具 | 说明 |
|---|---|
list_schemas | 列出数据库架构。默认情况下排除系统架构。 |
list_tables | 列出具有行数和大小的表。可选地包括视图。 |
describe_table | 获取表的列、约束和索引。 |
list_databases | 列出所有数据库及其所有者、编码和大小。 |
管理工具
| 工具 | 说明 |
|---|---|
get_connection_status | 获取池统计信息、隧道状态和连接信息。 |
list_active_connections | 显示来自的活动连接 pg_stat_activity. |
list_long_running_queries | 查找运行时间超过阈值的查询。 |
get_database_version | 获取PostgreSQL服务器版本。 |
get_database_size | 获取数据库大小和最大表。 |
get_table_stats | 获取真空/分析统计数据并扫描表格计数。 |
______________________________________________________________________
环境变量
数据库连接
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
DATABASE_URI | 是\* | -- | 完整连接字符串（例如。， postgresql://user:pass@host:5432/db) |
DATABASE_HOST | 是\* | -- | 数据库主机名 |
DATABASE_PORT | 没有 | 5432 | 数据库端口 |
DATABASE_NAME | 是\* | -- | 数据库名称 |
DATABASE_USER | 是\* | -- | 数据库用户名 |
DATABASE_PASSWORD | 是\* | -- | 数据库密码 |
\*要么 DATABASE_URI 或者需要所有单独的连接变量。
SSL配置
| 变量 | 默认值 | 描述 |
|---|---|---|
DATABASE_SSL | 汽车 | true 或 false。非本地主机自动启用。 |
DATABASE_SSL_CA | -- | CA证书包的路径 |
DATABASE_SSL_REJECT_UNAUTHORIZED | true | 设置 false 允许自签名证书 |
SSH隧道
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
SSH_ENABLED | 没有 | false | 设置 true 启用SSH隧道 |
SSH_HOST | 是\* | -- | SSH服务器主机名 |
SSH_PORT | 没有 | 22 | SSH服务器端口 |
SSH_USER | 是\* | -- | SSH用户名 |
SSH_PRIVATE_KEY_PATH | 是\*\* | -- | 私钥文件路径 |
SSH_PRIVATE_KEY_PASSPHRASE | 否 | -- | 加密密钥的密码 |
SSH_PASSWORD | 是\*\* | -- | SSH密码（密钥替代） |
SSH_STRICT_HOST_KEY | 没有 | true | 根据known_hosts验证主机密钥 |
SSH_TRUST_ON_FIRST_USE | 没有 | true | 自动添加未知主机（启用严格时） |
SSH_KNOWN_HOSTS_PATH | 没有 | ~/.ssh/known_hosts | 自定义known_hosts文件 |
SSH_KEEPALIVE_INTERVAL | 没有 | 10000 | 保持活动间隔（毫秒） |
SSH_MAX_RECONNECT_ATTEMPTS | 没有 | 5 | 最大重新连接尝试次数(-1 无限制） |
\*需要时 SSH_ENABLED=true \*\*要么 SSH_PRIVATE_KEY_PATH 或 SSH_PASSWORD 是必需的
查询行为
| 变量 | 默认值 | 描述 |
|---|---|---|
READ_ONLY | true | 阻止数据修改。集 false 允许写入。 |
MAX_ROWS | 1000 | 每个查询返回的最大行数 |
QUERY_TIMEOUT | 30000 | 查询超时（毫秒） |
MAX_CONCURRENT_QUERIES | 10 | 最大并发查询数 |
POOL_DRAIN_TIMEOUT_MS | 5000 | 重新连接时排水池超时 |
HTTP服务器（仅限流式HTTP）
| 变量 | 默认值 | 描述 |
|---|---|---|
PORT | 3000 | HTTP服务器端口 |
MCP_HOST | 0.0.0.0 | HTTP服务器绑定地址 |
MCP_AUTH_MODE | none | 身份验证模式： none 或 oauth |
MCP_STATELESS | true | 无状态模式（每个请求重新初始化） |
MCP_SERVER_POOL_SIZE | 4 | 无状态模式的服务器实例 |
MCP_SESSION_TTL_MINUTES | 30 | 状态模式的会话TTL |
MCP_SESSION_CLEANUP_INTERVAL_MS | 300000 | 会话清理间隔 |
MCP_ALLOWED_ORIGINS | -- | 允许使用逗号分隔的CORS源(* 任何） |
MCP_ALLOWED_HOSTS | -- | 允许使用逗号分隔的主机头 |
OAuth（Auth0）
| 变量 | 必填 | 描述 |
|---|---|---|
AUTH0_DOMAIN | 是\* | Auth0租户域（例如。， tenant.us.auth0.com) |
AUTH0_AUDIENCE | 是\* | Auth0 API标识符/受众 |
MCP_RESOURCE_DOCUMENTATION | 否 | API文档的URL（RFC 9728） |
\*需要时 MCP_AUTH_MODE=oauth
______________________________________________________________________
文档
| 指南 | 说明 |
|---|---|
| STDIO设置 | Claude桌面和本地开发 |
| 可流式传输的HTTP | HTTP服务器设置和配置 |
| 服务器安装程序 | 使用nginx和SSL部署到生产环境 |
| ChatGPT设置 | 完成ChatGPT的Auth0 OAuth设置 |
______________________________________________________________________
码头工人
STDIO服务器
docker build --target runtime -t postgresql-mcp .
docker run -e DATABASE_URI="postgresql://..." postgresql-mcpHTTP服务器
docker build --target runtime-http -t postgresql-mcp-http .
docker run -p 3000:3000 -e DATABASE_URI="postgresql://..." postgresql-mcp-http______________________________________________________________________
发展
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Type check
npm run typecheck
# Lint
npm run lint