使用说明

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-mcp

HTTP服务器

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