Postgres MCP

English | 🌐 Português

Postgres MCP 🔌 PostgreSQL 的原生 MCP 服务——运行时从 .env 读取凭据，支持灵活的键映射、可配置的工具选择，并且默认采用只读模式。

---

✨ 功能介绍

大多数大模型通过猜测与数据库交互——假定表名、编造列名，并编写可能执行失败或暴露敏感数据的查询。Postgres MCP 为大模型提供了一个结构化且安全的接口，让它在操作数据库前真正了解数据库，从而解决这一问题。

它基于 @modelcontextprotocol/sdk 和 pg 构建，提供：

• 🧠 语义知识图谱——大模型可获取完整的数据库映射，包括架构、表、列、外键、推断出的关系、风险级别和业务领域；这些信息来自真实架构，而非凭空编造
• 🛡️ 默认只读——不会写入、执行 DDL 或任意 SQL，除非你明确选择启用；pg_classify_query_risk 可让大模型在运行查询前检查其安全性
• 🔐 运行时解析凭据——启动时从 .env 读取凭据；mcp.json 中不会保存任何敏感信息
• 🎯 明确选择工具——每个工具都需通过 tool=<name> 参数主动启用，因此大模型只能看到你选择公开的工具

---

📋 要求

• ⚙️ Node.js >= 18
• 📄 包含数据库凭据的 .env 文件（可位于项目树中的任意位置——参见 .env 文件发现）

---

🚀 安装

使用此软件包有两种方式。请选择最适合你工作流的方式。

选项 1 - 无需安装（通过 npx，推荐快速开始）

无需安装。npx 会按需下载并运行软件包。将 -y 作为第一个参数，以跳过确认提示。

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@edelciomolina/postgres-mcp"
      ],
      "env": {
        "MCP_KEY_HOST":    "DB_HOST",
        "MCP_KEY_PORT":    "DB_PORT",
        "MCP_KEY_NAME":    "DB_NAME",
        "MCP_KEY_SSLMODE": "DB_SSLMODE",
        "MCP_KEY_USER":    "DB_USER",
        "MCP_KEY_PASS":    "DB_PASS"
      }
    }
  }
}

这会使用默认的只读工具集启动服务——无需 tool= 参数。若要启用可写工具，请参阅可写工具。

💡 使用 Supabase、Neon、Railway 或其他只提供连接字符串的平台？ 使用 MCP_KEY_URL 指向 DATABASE_URL（或平台使用的其他变量名）。服务会优先使用 URL，并忽略各个独立变量。请参阅通过 URL 连接。

---

选项 2 - 通过 VS Code 安装（MCP 扩展市场）

VS Code 支持直接在编辑器中发现并安装 MCP 服务，无需使用终端。

1. 打开命令面板（Mac 上按 Cmd+Shift+P / Windows/Linux 上按 Ctrl+Shift+P）
2. 运行 MCP: Add Server
3. 选择 "Browse MCP Servers"（或 "From registry"，具体取决于 VS Code 版本）
4. 搜索 postgres-mcp 或 edelciomolina
5. 选择 Postgres MCP 并按照说明操作 - VS Code 会自动将条目添加到 mcp.json

💡 你也可以通过 Copilot 聊天图标 → 管理 MCP 服务 打开 MCP 服务面板，随时浏览、启用或禁用服务。

安装后，编辑生成的 .vscode/mcp.json 条目，添加 tool= 参数和 env 键映射，如下方用法部分所示。

---

🚀 在 VS Code 中使用（mcp.json）

只读（默认 - 无需 tool= 参数）：

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["@edelciomolina/postgres-mcp"],
      "env": {
        "MCP_KEY_HOST":    "DB_HOST",
        "MCP_KEY_PORT":    "DB_PORT",
        "MCP_KEY_NAME":    "DB_NAME",
        "MCP_KEY_SSLMODE": "DB_SSLMODE",
        "MCP_KEY_USER":    "DB_USER",
        "MCP_KEY_PASS":    "DB_PASS"
      }
    }
  }
}

启用写入工具（需要明确选择启用）：

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@edelciomolina/postgres-mcp",
        "tool=pg_manage_schema",
        "tool=pg_manage_indexes"
      ],
      "env": {
        "POSTGRES_MCP_ALLOW_WRITE": "true",
        "MCP_KEY_HOST":    "DB_HOST",
        "MCP_KEY_PORT":    "DB_PORT",
        "MCP_KEY_NAME":    "DB_NAME",
        "MCP_KEY_SSLMODE": "DB_SSLMODE",
        "MCP_KEY_USER":    "DB_USER",
        "MCP_KEY_PASS":    "DB_PASS"
      }
    }
  }
}

⚠️ 支持写入的工具需要在 env 中设置 POSTGRES_MCP_ALLOW_WRITE=true。否则，服务会在启动时退出。

项目根目录下对应的 .env 文件：

DB_HOST=db.your-project.supabase.co
DB_PORT=5432
DB_NAME=postgres
DB_SSLMODE=require
DB_USER=readonly_user
DB_PASS=your_password

---

⚙️ mcp.json 配置的工作方式

🗝️ env - 凭据键映射

env 块不包含实际凭据，而是将每个 MCP_KEY_* 映射到 .env 文件中的变量名。

env 中的键	指向 .env 变量	示例值
MCP_KEY_URL	DATABASE_URL	postgresql://user:pass@host:5432/db?sslmode=require
MCP_KEY_HOST	DB_HOST	db.example.supabase.co
MCP_KEY_PORT	DB_PORT	5432
MCP_KEY_NAME	DB_NAME	postgres
MCP_KEY_SSLMODE	DB_SSLMODE	require
MCP_KEY_USER	DB_USER	readonly_user
MCP_KEY_PASS	DB_PASS	secret

优先级：如果存在 MCP_KEY_URL（或 DATABASE_URL），服务会直接使用该 URL，并忽略单独的凭据键。

这种间接映射方式让你可以在 .env 中使用任意变量名 - 当多个服务使用不同的命名约定、需要共用一个 .env 时尤其方便。

🔧 args - 通过 tool= 前缀选择工具

每个启用的 MCP 工具都以单独的参数声明，格式为 tool=<name>：

"args": [
  "-y",
  "@edelciomolina/postgres-mcp",
  "tool=pg_manage_schema",
  "tool=pg_manage_indexes"
]

这样一来，工具列表就能直接在 mcp.json 中明确列出，方便审查 - 不存在隐藏的配置文件。🔍

---

🔗 通过 URL 连接（DATABASE_URL）

除了单独的凭据外，你还可以提供完整的连接字符串 - 这是 Supabase、Neon 和 Railway 等平台上的标准格式。

.env：

DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require

mcp.json：

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@edelciomolina/postgres-mcp"],
      "env": {
        "MCP_KEY_URL": "DATABASE_URL"
      }
    }
  }
}

通过 MCP_KEY_URL 映射的变量优先级高于其他键（MCP_KEY_HOST、MCP_KEY_PORT 等）。如果存在 URL，其他变量将被忽略。

如果平台使用了其他名称（例如 DB_URL），只需调整映射：

"MCP_KEY_URL": "DB_URL"

---

🛡️ 为什么默认采用只读模式

如果省略所有 tool= 参数，服务将以精选的只读工具集启动——其中包含所有可检索、分析或解释数据的工具，但不包含任何可修改数据的工具。

✅ 默认包含（只读）：

pg_execute_query       pg_manage_query        pg_inspect_schema
pg_get_setup_instructions                     pg_analyze_database
pg_monitor_database                           pg_debug_database
pg_inspect_database_graph                     pg_describe_table_semantics
pg_find_related_tables                        pg_classify_query_risk

💡 pg_execute_query 会在查询数据库前，拒绝 INSERT、UPDATE、DELETE、DDL、ANALYZE、VACUUM、EXPLAIN ANALYZE 及其他写入或维护命令。

💡 pg_inspect_schema 提供只读的架构自省功能（get_info、get_enums）。如需执行 DDL 操作，请使用 pg_manage_schema 并明确选择启用。

⚠️ 默认排除——需要 tool= 参数且设置 POSTGRES_MCP_ALLOW_WRITE=true：

工具	操作
pg_manage_schema	CREATE TABLE、ALTER TABLE、CREATE TYPE
pg_manage_indexes	CREATE INDEX、DROP INDEX、REINDEX
pg_manage_constraints	ADD CONSTRAINT、DROP CONSTRAINT
pg_manage_functions	CREATE FUNCTION、DROP FUNCTION
pg_manage_triggers	CREATE TRIGGER、DROP TRIGGER、启用/禁用
pg_manage_rls	ENABLE/DISABLE RLS、CREATE/ALTER/DROP POLICY
pg_manage_users	CREATE/DROP/ALTER USER、GRANT、REVOKE
pg_execute_mutation	INSERT / UPDATE / DELETE / UPSERT
pg_execute_sql	支持事务的任意 SQL

---

📍 .env 文件查找

服务按以下顺序查找 .env 文件：

1. env-file=<path> 参数——相对于 cwd 的显式路径；优先级最高
2. 向上搜索——从 cwd 开始，逐级搜索父目录，直到找到 .env 或到达文件系统根目录

如果找不到 .env，服务将退出并显示明确的错误消息。

单体仓库和子文件夹

VS Code 启动 MCP 进程时，cwd 通常是工作区根目录。如果你的 .env 位于子文件夹中（例如 functions/.env），请使用 env-file= 明确指定路径：

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@edelciomolina/postgres-mcp",
        "env-file=functions/.env"
      ],
      "env": {
        "MCP_KEY_HOST":    "DB_HOST",
        "MCP_KEY_PORT":    "DB_PORT",
        "MCP_KEY_NAME":    "DB_NAME",
        "MCP_KEY_SSLMODE": "DB_SSLMODE",
        "MCP_KEY_USER":    "DB_USER",
        "MCP_KEY_PASS":    "DB_PASS"
      }
    }
  }
}

💡 向上搜索可自动处理常见情况。需要显式控制时（CI、单体仓库、Docker 绑定挂载），请使用 env-file=。

---

🧰 可用工具

只读（默认启用）

工具	描述
pg_execute_query	SELECT / COUNT / EXISTS，并防护写入操作和多语句
pg_manage_query	EXPLAIN 计划、慢查询分析、pg_stat_statements
pg_inspect_schema	架构信息和 ENUM 类型（只读自省）
pg_get_setup_instructions	各平台的设置说明
pg_analyze_database	性能、配置和存储分析
pg_monitor_database	实时监控连接、查询、锁和复制
pg_debug_database	诊断连接、锁、性能和复制问题
pg_inspect_database_graph	构建完整的数据库知识图谱：架构、表、列、FK、索引、推断关系和业务领域
pg_describe_table_semantics	提供表的语义上下文说明：风险级别、列角色、敏感列和相关表
pg_find_related_tables	通过显式 FK 和推断的命名模式查找与指定表相关的表，并说明关联路径
pg_classify_query_risk	对查询风险进行分类（safe / warning / review / blocked），但不执行查询

可写（通过 tool= 参数和 POSTGRES_MCP_ALLOW_WRITE=true 启用）

工具	描述
pg_manage_schema	查看 Schema 信息、创建/修改表、管理 ENUM
pg_manage_indexes	列出、创建、删除索引，重新索引，分析索引使用情况
pg_manage_constraints	列出、创建和删除约束及外键
pg_manage_functions	列出、创建和删除函数及存储过程
pg_manage_triggers	列出、创建、删除、启用/禁用触发器
pg_manage_rls	行级安全策略
pg_manage_users	用户权限、创建/删除/修改用户、授权/撤销授权
pg_execute_mutation	使用参数化查询执行 INSERT / UPDATE / DELETE / UPSERT
pg_execute_sql	执行任意 SQL，可选支持事务

---

🧠 语义层

四个 pg_*_graph / pg_*_semantics / pg_*_risk 工具会在运行时构建数据库的内存知识图谱。这会为大模型提供一份结构化地图，涵盖 Schema、表、列、外键、推断出的关系、风险等级和业务领域，且不会对你的数据执行任何查询。

所有推断字段（列的语义角色、表的可能类型、推断出的关系）都会明确标记，让大模型知道应将它们视为提示，而非 Schema 事实。

可选配置（mcp-config.json）

在 .env 文件旁放置一个 mcp-config.json 文件，以调整语义层和安全限制。所有字段均为可选项——省略此文件时将应用安全默认值。

{
  "security": {
    "defaultLimit": 100,
    "maxLimit": 1000,
    "blockedSchemas": ["pg_catalog", "information_schema"],
    "blockedTables": [],
    "requireLimit": true
  },
  "semanticLayer": {
    "enabled": true,
    "inferRelationsWithoutForeignKeys": true,
    "inferBusinessEntities": true,
    "sensitiveKeywords": ["password", "secret", "token", "api_key", "ssn", "hash"]
  }
}

---

🏗️ 架构

如需详细了解 MCP 客户端、代理和 PostgreSQL 之间的通信流程（包括完整的时序图），请参阅 ARCHITECT.md。

---

📄 许可证

MIT © Edelcio Molina