指南：配置 mcp-server-postgres 连接

mcp-server-postgres 让 AI Agent 能够安全地查询 PostgreSQL 数据库。本文详细讲解配置方法和安全最佳实践。

什么是 postgres 工具？

postgres 工具提供以下能力：

• query: 执行 SELECT 查询
• execute: 执行 INSERT/UPDATE/DELETE
• 支持参数化查询防止 SQL 注入

基本配置

安装

npx -y @modelcontextprotocol/server-postgres postgresql://localhost/dbname

Claude Code 配置

方式一：直接连接字符串（不推荐）

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/dbname"
      ]
    }
  }
}

方式二：环境变量（推荐）

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/dbname"
      ],
      "env": {
        "PGUSER": "dbuser",
        "PGPASSWORD": "dbpassword",
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGDATABASE": "dbname"
      }
    }
  }
}

连接字符串安全写法

标准格式

postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]

示例

# 本地数据库
postgresql://localhost/mydb

# 带用户名密码
postgresql://user:pass@localhost:5432/mydb

# SSL 连接
postgresql://user@host/mydb?sslmode=require

SSL 模式

模式	说明	适用场景
disable	不使用 SSL	本地开发
allow	优先非 SSL	测试环境
prefer	优先 SSL	生产环境
require	必须使用 SSL	安全要求高的环境
verify-ca	验证 CA	高安全环境
verify-full	验证主机名和 CA	最高安全

postgresql://user@host/mydb?sslmode=require

数据库权限配置

创建只读用户（推荐）

-- 创建只读角色
CREATE ROLE read_only WITH LOGIN PASSWORD secure_password;

-- 授予数据库连接权限
GRANT CONNECT ON DATABASE mydb TO read_only;

-- 授予 schema 使用权限
GRANT USAGE ON SCHEMA public TO read_only;

-- 授予表查询权限
GRANT SELECT ON ALL TABLES IN SCHEMA public TO read_only;

-- 自动授予未来创建的表
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO read_only;

创建读写用户

-- 创建读写角色
CREATE ROLE read_write WITH LOGIN PASSWORD secure_password;

-- 授予连接权限
GRANT CONNECT ON DATABASE mydb TO read_write;

-- 授予 schema 权限
GRANT USAGE, CREATE ON SCHEMA public TO read_write;

-- 授予表权限
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO read_write;

-- 授予序列权限
GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO read_write;

安全最佳实践

1. 使用只读用户

生产环境强烈推荐使用只读用户，避免 AI 意外修改数据。

2. 限制访问的表

-- 只授予特定表的权限
GRANT SELECT ON users, orders, products TO read_only;
-- 不授予敏感表
-- REVOKE ALL ON passwords, api_keys FROM read_only;

3. 使用连接池

对于高并发场景，使用连接池：

postgresql://user:pass@localhost/mydb?pool_size=10&pool_timeout=30

4. 网络隔离

• 数据库不暴露公网
• 使用 VPN 或私有网络
• 配置防火墙规则

验证配置

1. 重启 Claude Code
2. 输入 /mcp 查看 postgres 工具
3. 测试查询：

   请查询 users 表的前 10 条记录
   

常见问题

Connection refused

• 数据库服务未启动
• 端口配置错误
• 防火墙阻止

Authentication failed

• 用户名/密码错误
• pg_hba.conf 配置问题

Invalid params

• 缺少 connection_string
• 连接字符串格式错误

下一步

• Connection refused 错误排查
• Authentication failed 错误排查
• 文件系统工具配置