postgres ssh-mcp
支持SSH隧道的PostgreSQL跨平台MCP服务器。适用于macOS、Linux和Windows。
概述
postgres-ssh-mcp 公开了允许AI工具查询和内省PostgreSQL数据库的MCP工具。它支持三种连接模式：
连接模式
| 模式 | 激活时 | 连接方式 |
|---|---|---|
| 直接的 | 未设置SSH变量 | 直接连接到Postgres（无隧道） |
| SSH配置 | SSH_HOST 已设置 | 读取 ~/.ssh/config 对于给定的别名；使用其 HostName, User, IdentityFile等等。 |
| 显式SSH | SSH_HOSTNAME + SSH_USER 已设置 | 使用环境变量中的值打开SSH隧道 |
使用AI工具
任何MCP兼容工具
Claude Desktop、Cursor和Windsurf等工具使用JSON配置文件。在下面添加条目 mcpServers:
{
"mcpServers": {
"postgres-ssh-mcp": {
"command": "npx",
"args": ["-y", "postgres-ssh-mcp"],
"env": {
"DB_HOST": "localhost",
"DB_NAME": "mydb",
"DB_USER": "dbuser",
"DB_PASSWORD": "dbpassword",
// If you have an SSH config alias:
"SSH_HOST": "my-bastion",
// Or if you need explicit SSH:
"SSH_HOSTNAME": "127.0.0.1",
"SSH_USER": "mybastionuser",
"SSH_IDENTITY_FILE": "~/.ssh/mybastionkey", // optional if you use the default key path
"SSH_KEY_PASSPHRASE": "mypassphrase", // optional, if your private key is encrypted
"SSH_PORT": "1234", // defaults to 22
}
}
}
}对于SSH隧道连接，添加 SSH_HOST （SSH配置别名）或 SSH_HOSTNAME + SSH_USER （显式凭据）到 env 块。
克劳德代码
使用 claude mcp add 注册服务器。所有环境变量必须通过传递 --env 旗帜。
claude mcp add --transport stdio postgres-ssh-mcp \
--env DB_HOST=localhost \
--env DB_NAME=mydb \
--env DB_USER=dbuser \
--env DB_PASSWORD=dbpassword \
-- npx -y postgres-ssh-mcp提示： 您可以包括 --scope project 将服务器仅添加到当前项目中。
工具
| 工具 | 说明 |
|---|---|
run_query | 执行SQL查询（默认情况下为只读；请参阅 DB_READ_ONLY).支持参数化查询 $1, $2, ... 占位符 |
explain_query | 获取SQL查询的执行计划。支持所有PostgreSQL EXPLAIN选项（分析、缓冲、定时等）和输出格式（文本、JSON、YAML、XML） |
list_schemas | 列出数据库中的所有架构 |
list_tables | 列出架构中的表（默认值： public) |
describe_table | 显示表的列、类型和可空性 |
get_connection_status | 显示连接池统计信息、数据库版本、大小和服务器配置 |
深度防御查询安全
这是设置的关键功能 postgres-ssh-mcp 除了其他PostgreSQL MCP服务器之外。它是唯一一个通过安全机制的组合来实施多层保护以防止意外数据修改的系统。
- AST级SQL验证 使用
pgsql-parser和@pgsql/traverse--将SQL解析为抽象语法树并遍历它以检测突变（包括CTE中的隐藏突变），SELECT INTO以及锁定条款。仅SELECT和EXPLAIN允许发表声明。 - 危险功能denylist --阻止250多个PostgreSQL函数，即使在只读事务中也会产生副作用，包括
pg_sleep,nextval,pg_notify、文件I/O功能、咨询锁和复制控制。 - 只读事务包装 --所有查询都在内部执行
BEGIN TRANSACTION READ ONLY自动ROLLBACK. - 单一声明执行 --多语句查询在执行前被拒绝。
_注： 不建议禁用这些安全机制，但是，您可以通过设置 DB_READ_ONLY=false，它授予AI工具对数据库的完全写入权限。_
环境变量
这些都是可用于配置此MCP服务器的环境变量。
必需
| 变量 | 描述 |
|---|---|
DB_HOST | Postgres主机或RDS端点 |
DB_NAME | 数据库名称 |
DB_USER | 数据库用户 |
DB_PASSWORD | 数据库密码 |
可选的
| 变量 | 默认值 | 描述 |
|---|---|---|
ALLOWED_TOOLS | _（全部）_ | 以逗号分隔的要注册的工具列表。未设置时，所有工具都可用。案件敏感。例子： run_query,describe_table |
DB_PORT | 5432 | Postgres港口 |
DB_READ_ONLY | true | 设置为 false 允许写查询(run_query 仅） |
DB_SSL | false | 设置为 true 为数据库连接启用TLS |
DB_SSL_CA | -- | 用于SSL验证的自定义CA证书文件（PEM）的路径 |
DB_SSL_REJECT_UNAUTHORIZED | true | 设置为 false 跳过SSL证书验证（不安全） |
DB_MAX_ROWS | 1000 | 每个查询返回的最大行数。在只读模式下使用基于光标的获取 |
DB_CONNECTION_POOL_SIZE | 5 | 池中的最大连接数 |
DB_CONNECTION_TIMEOUT_MS | 10000 | 等待来自池的连接的毫秒数 |
DB_QUERY_TIMEOUT_MS | 15000 | 强制取消查询前的毫秒 |
DB_POOL_DRAIN_TIMEOUT_MS | 5000 | 在重新连接期间等待旧池排空的毫秒数（0表示从不等待） |
SSH_HOST | -- | SSH配置别名（读取 ~/.ssh/config) |
SSH_HOSTNAME | -- | Bastion主机名或IP |
SSH_USER | -- | SSH登录用户 |
SSH_PORT | 22 | SSH端口 |
SSH_STRICT_HOST_KEY_CHECKING | true | 启用或禁用严格主机检查 |
SSH_IDENTITY_FILE | -- | 绝对路径或 ~/... 到私钥文件 |
SSH_KEY_PASSPHRASE | -- | 加密私钥的密码 |
SSH_PASSWORD | -- | SSH密码（基于密钥的身份验证的替代方案） |
SSH_KEEPALIVE_INTERVAL_MS | disabled | SSH保活探测之间的毫秒数（如果设置：最小1000） |
SSH_KEEPALIVE_COUNT_MAX | 3 | 在断开连接之前，最多可进行未应答的保活探测 |
SSH_TRUST_ON_FIRST_USE | true | 在首次连接时自动接受并保存未知的SSH主机密钥 |
SSH_KNOWN_HOSTS_PATH | -- | 自定义known_hosts文件的路径（默认值： ~/.ssh/known_hosts) |
SSH_MAX_RECONNECT_ATTEMPTS | 5 | SSH重新连接的最大尝试次数（-1表示无限制，0表示禁用） |
发展
复制示例env文件并填写您的值：
git clone https://github.com/SecretX33/postgres-ssh-mcp.git
cd postgres-ssh-mcp
npm install
npm run build编译后的服务器被写入 dist/index.js.
复制示例env文件并填写您的值：
cp .env.example .env
# edit .env然后以监视模式运行（自动加载 .env):
npm run dev许可证
麻省理工学院