如何设置 PostgreSQL MCP Server (2026)
让 AI 助手直接访问您的 PostgreSQL 数据库
开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始,扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
如何设置 PostgreSQL MCP 服务器 (2026)
PostgreSQL MCP 服务器允许像 Claude 这样的 AI 助手直接查询您的 PostgreSQL 数据库、查看模式(schemas)、列出表并分析数据——这一切都通过自然语言对话完成。您无需手动将查询结果复制到聊天窗口,而是让 Claude 获得对数据库的直接且受控的访问权限。本指南涵盖了安装、配置和安全最佳实践。
什么是 PostgreSQL MCP 服务器?
MCP (Model Context Protocol) 是 Anthropic 发布的开放标准,用于将 AI 助手连接到外部工具和数据源。PostgreSQL MCP 服务器将您的数据库公开为一组 Claude 可以调用的工具:
| 工具 | 描述 |
|---|---|
query |
执行只读 SQL 查询 |
list_tables |
列出模式中的所有表 |
describe_table |
获取表的列名、类型和约束 |
list_schemas |
列出数据库中的所有模式 |
get_table_stats |
获取行数和基础统计信息 |
当 Claude 连接到 PostgreSQL MCP 服务器后,您可以提出自然语言问题,例如“本月按收入排名前 10 的客户是谁?”,Claude 将编写 SQL、执行并展示结果。
前置条件
- PostgreSQL 12 或更高版本正在运行且可访问
- Node.js 18 或更高版本(用于运行 MCP 服务器)
- Claude Desktop 或 Claude Code (兼容 MCP 的客户端)
- 拥有适当权限的 PostgreSQL 用户
检查您的版本:
psql --version
# psql (PostgreSQL) 16.x
node --version
# v20.x.x 或更高
第 1 步:创建只读数据库用户
切勿使用超级用户或具有写入权限的账户连接 MCP 服务器。请创建一个专用的只读用户:
-- 以管理员身份连接 PostgreSQL
psql -U postgres
-- 创建只读角色
CREATE ROLE mcp_reader WITH LOGIN PASSWORD 'your_secure_password';
-- 授予连接数据库的权限
GRANT CONNECT ON DATABASE your_database TO mcp_reader;
-- 授予模式的使用权限
GRANT USAGE ON SCHEMA public TO mcp_reader;
-- 授予对所有现有表的 SELECT 权限
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_reader;
-- 自动为未来的表授予 SELECT 权限
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO mcp_reader;
-- 可选:授予对其他模式的访问权限
GRANT USAGE ON SCHEMA analytics TO mcp_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA analytics TO mcp_reader;
验证该用户是否仅具有读取权限:
psql -U mcp_reader -d your_database -c "SELECT 1;"
# 应当执行成功
psql -U mcp_reader -d your_database -c "DROP TABLE users;"
# 应当失败并提示权限被拒绝 (permission denied)
第 2 步:安装 PostgreSQL MCP 服务器
社区维护了多个 PostgreSQL MCP 服务器包。最常用的是 @modelcontextprotocol/server-postgres:
# 全局安装
npm install -g @modelcontextprotocol/server-postgres
# 或者使用 npx (无需安装)
npx @modelcontextprotocol/server-postgres
第 3 步:配置 Claude Desktop
将 PostgreSQL MCP 服务器添加到您的 Claude Desktop 配置中。
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"postgresql": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://mcp_reader:your_secure_password@localhost:5432/your_database"
]
}
}
}
使用环境变量(推荐)
为了避免在配置文件中存放明文凭据:
{
"mcpServers": {
"postgresql": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres"
],
"env": {
"DATABASE_URL": "postgresql://mcp_reader:your_secure_password@localhost:5432/your_database"
}
}
}
}
连接到远程数据库
对于远程数据库,请使用包含 SSL 的完整连接字符串:
{
"mcpServers": {
"postgresql": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres"
],
"env": {
"DATABASE_URL": "postgresql://mcp_reader:password@db.example.com:5432/mydb?sslmode=require"
}
}
}
}
第 4 步:为 Claude Code 进行配置
如果您使用 Claude Code (命令行界面),请将 MCP 服务器添加到您项目的 .claude/settings.json 中:
{
"mcpServers": {
"postgresql": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres"
],
"env": {
"DATABASE_URL": "postgresql://mcp_reader:password@localhost:5432/your_database"
}
}
}
}
或者在 ~/.claude/settings.json 中全局配置,使其在所有项目中可用。
第 5 步:重启并验证
保存配置后:
- 完全退出 Claude Desktop(不只是关闭窗口)
- 重新打开 Claude Desktop
- 查找数据库图标或 MCP 工具指示器
- 询问 Claude:“我的数据库中有哪些表?”
Claude 应当返回您的表列表。如果没有,请查看下方的故障排查部分。
查询示例
连接后,您可以向 Claude 提出自然语言问题:
模式探索
"列出 public 模式中所有的表及其行数"
"描述 users 表——给我看所有列及其类型"
数据分析
"2026 年 1 月总收入排名前 10 的产品有哪些?"
"显示过去 30 天的每日注册趋势"
复杂查询
"找出过去 7 天内注册但未进行过购买的所有用户。
请包含他们的邮箱和注册日期。"
"计算过去 6 个月活跃用户的月环比增长率"
Claude 将编写适当的 SQL,通过 MCP 服务器执行,并以易读的格式展示结果。
安全最佳实践
| 实践方案 | 原因 | 实施方法 |
|---|---|---|
| 使用只读用户 | 防止数据被意外篡改 | 仅授予 GRANT SELECT |
| 限制特定模式 | 减少数据暴露 | 选择性地使用 GRANT USAGE ON SCHEMA |
| 使用连接池 | 防止连接耗尽 | 使用 PgBouncer 或内置连接池 |
| 设置语句超时 | 防止长时间运行的查询 | 指令:ALTER ROLE mcp_reader SET statement_timeout = '30s' |
| 排除敏感表 | 保护 PII 和凭据 | 对特定表执行 REVOKE SELECT |
| 使用 SSL | 加密传输中的数据 | 在连接字符串中加入 ?sslmode=require |
| 审计查询 | 监控 Claude 访问的内容 | 为 MCP 角色启用 log_statement = 'all' |
限制对敏感表的访问
-- 撤回对包含敏感数据表的访问权限
REVOKE SELECT ON TABLE user_credentials FROM mcp_reader;
REVOKE SELECT ON TABLE payment_methods FROM mcp_reader;
REVOKE SELECT ON TABLE api_keys FROM mcp_reader;
-- 或者创建一个仅公开安全列的视图
CREATE VIEW safe_users AS
SELECT id, username, created_at, last_login
FROM users;
GRANT SELECT ON safe_users TO mcp_reader;
设置查询限制
-- 为 MCP 用户设置 30 秒超时
ALTER ROLE mcp_reader SET statement_timeout = '30s';
-- 限制返回的行数所需的内存
ALTER ROLE mcp_reader SET work_mem = '64MB';
进阶:自定义 PostgreSQL MCP 服务器
如果您需要更多控制权,可以构建一个包含额外逻辑的自定义 MCP 服务器来包装 PostgreSQL:
// custom-pg-mcp.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import pg from "pg";
const pool = new pg.Pool({
connectionString: process.env.DATABASE_URL,
max: 5,
statement_timeout: 30000
});
const server = new Server({
name: "custom-postgres",
version: "1.0.0"
}, {
capabilities: { tools: {} }
});
server.setRequestHandler("tools/list", async () => ({
tools: [
{
name: "query",
description: "Execute a read-only SQL query",
inputSchema: {
type: "object",
properties: {
sql: { type: "string", description: "SQL SELECT query" }
},
required: ["sql"]
}
}
]
}));
server.setRequestHandler("tools/call", async (request) => {
const { name, arguments: args } = request.params;
if (name === "query") {
const sql = args.sql.trim();
// 仅允许 SELECT 和 WITH (CTE) 语句
if (!/^(SELECT|WITH)\b/i.test(sql)) {
return {
content: [{ type: "text", text: "Error: Only SELECT queries allowed" }],
isError: true
};
}
// 拦截危险关键词
const blocked = /\b(DROP|DELETE|UPDATE|INSERT|ALTER|TRUNCATE|GRANT|REVOKE)\b/i;
if (blocked.test(sql)) {
return {
content: [{ type: "text", text: "Error: Blocked keyword detected" }],
isError: true
};
}
try {
const result = await pool.query(sql);
return {
content: [{
type: "text",
text: JSON.stringify(result.rows, null, 2)
}]
};
} catch (error) {
return {
content: [{ type: "text", text: `Query error: ${error.message}` }],
isError: true
};
}
}
});
const transport = new StdioServerTransport();
await server.connect(transport);
故障排查
| 问题 | 原因 | 解决方案 |
|---|---|---|
| "Connection refused" | PostgreSQL 未运行或端口错误 | 检查 pg_isready -h localhost -p 5432 |
| "Authentication failed" | 密码或用户名错误 | 直接使用 psql 验证凭据 |
| MCP 服务器未显示 | 配置文件错误 | 验证 JSON 语法;重启 Claude Desktop |
| "Permission denied for table" | 缺少 GRANT | 重新运行 GRANT SELECT ON ALL TABLES... |
| 查询超时 | 缺少 statement_timeout | 为角色设置 statement_timeout |
| "SSL required" | 远程数据库要求 SSL | 在连接字符串中添加 ?sslmode=require |
| 查询缓慢 | 缺少索引或表数据过大 | 添加索引;在查询中使用 LIMIT |
结论
PostgreSQL MCP 服务器改变了您通过 AI 与数据库交互的方式。Claude 可以直接查询您的数据、探索模式并帮助您分析结果,而无需在 SQL 客户端和聊天窗口之间切换——这一切都使用自然语言完成。关键在于通过只读用户和受限的表访问权限来建立预期的安全性。
对于那些正在构建数据驱动型应用,同时需要 AI 生成视觉内容(例如将分析数据转换为视频演示或生成基于图表的内容)的团队,Hypereal AI 提供了视频生成、图像合成和语音对话头像创建的 API,是您数据流水线的完美补充。
