如何设置 PostgreSQL MCP Server (2026)

如何设置 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，是您数据流水线的完美补充。

如何设置 PostgreSQL MCP 服务器 (2026)

什么是 PostgreSQL MCP 服务器？

工具	描述
`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

开始使用 Hypereal 构建

如何设置 PostgreSQL MCP 服务器 (2026)

什么是 PostgreSQL MCP 服务器？

前置条件

第 1 步：创建只读数据库用户

第 2 步：安装 PostgreSQL MCP 服务器

第 3 步：配置 Claude Desktop

使用环境变量（推荐）

连接到远程数据库

第 4 步：为 Claude Code 进行配置

第 5 步：重启并验证

查询示例

模式探索

数据分析

复杂查询

安全最佳实践

限制对敏感表的访问

设置查询限制

进阶：自定义 PostgreSQL MCP 服务器

故障排查

结论

相关文章

如何设置 Supabase MCP Server (2026)

如何从零开始构建 MCP Server (2026)

如何设置 Context7 MCP Server (2026)

立即开始构建

开始使用 Hypereal 构建

如何设置 PostgreSQL MCP 服务器 (2026)

什么是 PostgreSQL MCP 服务器？

前置条件

第 1 步：创建只读数据库用户

第 2 步：安装 PostgreSQL MCP 服务器

第 3 步：配置 Claude Desktop

使用环境变量（推荐）

连接到远程数据库

第 4 步：为 Claude Code 进行配置

第 5 步：重启并验证

查询示例

模式探索

数据分析

复杂查询

安全最佳实践

限制对敏感表的访问

设置查询限制

进阶：自定义 PostgreSQL MCP 服务器

故障排查

结论

相关文章

如何设置 Supabase MCP Server (2026)

如何从零开始构建 MCP Server (2026)

如何设置 Context7 MCP Server (2026)

立即开始构建