MCP Pg Metatool

mcp-pg元工具

PostgreSQL的模型上下文协议（MCP）服务器，使AI代理能够执行SQL查询并创建可重用的参数化查询工具。

特性

• 执行任意SQL 具有命名参数支持(:param_name 语法）
• 保存参数化查询 作为可重用的MCP工具，在会话中持久存在
• 数据库自检 用于探索模式、表、视图及其结构的工具
• 连接池 实现高效的数据库访问

安装

npm install
npm run build

配置

数据库连接

设置以下选项之一：

# Option 1: Connection URL (recommended)
export DATABASE_URL="postgresql://user:password@localhost:5432/dbname"

# Option 2: Individual variables
export PGHOST="localhost"
export PGPORT="5432"
export PGDATABASE="mydb"
export PGUSER="myuser"
export PGPASSWORD="mypassword"

可选设置

# SSL mode (disable, require, verify-ca, verify-full)
export PGSSLMODE="require"

# Connection pool size (default: 10)
export PG_POOL_MAX="10"

# Data directory for saved queries (default: ./data)
export MCP_PG_DATA_DIR="./data"

# Disable core tools: "none" (default), "management", or "all"
export DISABLE_CORE_TOOLS="none"

安全功能

两个选择加入控件，用于限制MCP服务器向代理公开的内容。 这些是深度防御，而不是主要控制。 限制代理可以做什么的权威方法是与一个专用的PostgreSQL角色连接，该角色的权限范围是适当的（例如。 GRANT SELECT ON ... TO readonly_role, GRANT SELECT (col1, col2) ON sensitive_table TO readonly_role).

# Block mutations at the tool layer. When enabled, every pooled connection
# runs `SET SESSION default_transaction_read_only = on`, so PostgreSQL itself
# rejects INSERT/UPDATE/DELETE/DDL/TRUNCATE — including writes smuggled
# inside CTEs (WITH x AS (UPDATE ...) SELECT ...).
export READONLY_MODE="true"

# Comma-separated list of sensitive columns to redact from tool responses.
# Format: schema.table.column
export FIELD_BLACKLIST="public.users.ssn,public.users.password_hash,public.payments.cc_number"

# Per-statement timeout in milliseconds. Sets `statement_timeout` on every
# pooled connection so PostgreSQL cancels any query that runs too long —
# applies to the agent's queries and to the server's own introspection lookups.
# Unset (or 0) means no timeout.
export QUERY_TIMEOUT_MS="30000"

# Auto-populate the field blacklist from the DB user's column-level GRANTs.
# At startup, runs `has_column_privilege(current_user, ...)` against every
# user-schema column and merges any denials into FIELD_BLACKLIST. Lets the
# tool-level filter track the DB ACL without maintaining two lists.
export AUTO_BLACKLIST_FROM_GRANTS="true"

这 list_inaccessible_columns 该工具根据需要向代理显示相同的信息，使其能够主动选择显式的列列表，而不是点击 SELECT * 权限错误。

只读警告。 PostgreSQL的只读事务模式仍然允许 SET, SHOW、临时表和写入 *其他* 数据库通过 dblink/FDW。使用DB角色权限进行权威锁定。

黑名单行为。 对于查询返回的每一列，服务器通过以下方式解析其来源 pg_class/pg_attribute 并删除任何符合以下条件的条目 schema.table.column 与黑名单匹配。匹配的列将以某种方式报告给代理 redactedColumns 阵列。计算/混叠输出（例如。 SELECT ssn AS x FROM users)无法解析为源列并回退到按输出名称匹配；这些报告如下 unresolvedRedactions 作为尽力而为的过滤器——依赖于列级别 GRANT/REVOKE 如果这个边缘案例对你来说很重要。黑名单也会过滤 describe_table / describe_view 输出，这样敏感的列名就不会通过内省泄露。

黑名单并不能阻止侧信道探测。 过滤器只检查返回的行，不检查查询本身。代理正在运行 SELECT id FROM users WHERE ssn = '123-45-6789' 即使没有，仍然可以通过观察行数来了解SSN是否存在 ssn 列始终返回。柱级 REVOKE SELECT (ssn) 在PostgreSQL中，两个读取都被阻止 *和* 对列进行过滤/排序/连接——这是缩小这一差距的唯一方法。将工具级黑名单视为显示层安全网，而不是访问控制。

用法

运行服务器

# Development
npm run dev

# Production
npm start

MCP客户端配置

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/path/to/mcp-pg-metatool/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/dbname"
      }
    }
  }
}

可用工具

查询执行

查询管理

数据库反思

示例

执行查询

Tool: execute_sql_query
Arguments:
  query: "SELECT * FROM users WHERE status = :status LIMIT :limit"
  params: { "status": "active", "limit": 10 }

保存可重用查询

Tool: save_query
Arguments:
  tool_name: "get_active_users"
  description: "Get active users with optional limit"
  sql_query: "SELECT id, name, email FROM users WHERE status = 'active' LIMIT :limit"
  parameter_schema: {
    "type": "object",
    "properties": {
      "limit": {
        "type": "integer",
        "default": 100,
        "description": "Maximum number of users to return"
      }
    }
  }

保存后， get_active_users 作为一种新工具，它可以在会话中持续使用。

探索数据库结构

Tool: list_tables
Arguments:
  schema_name: "public"

Tool: describe_table
Arguments:
  table_name: "users"
  schema_name: "public"

命名参数

SQL查询使用冒号前缀的命名参数，这些参数转换为PostgreSQL的位置 $1, $2, ... 执行时的语法：

-- You write:
SELECT * FROM orders WHERE user_id = :user_id AND status = :status

-- Executed as:
SELECT * FROM orders WHERE user_id = $1 AND status = $2

这避免了与PostgreSQL的冲突 :: 类型转换语法。

保存的查询格式

保存的查询以JSON文件存储在 data/tools/:

{
  "name": "get_user_orders",
  "description": "Get orders for a specific user",
  "sql_query": "SELECT * FROM orders WHERE user_id = :user_id",
  "sql_prepared": "SELECT * FROM orders WHERE user_id = $1",
  "parameter_schema": {
    "type": "object",
    "properties": {
      "user_id": { "type": "integer" }
    },
    "required": ["user_id"]
  },
  "parameter_order": ["user_id"]
}

发展

# Run in development mode with hot reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

许可证

麻省理工学院