AI导哈

PostgreSQL智能代理

mcp-server-postgres是一个智能数据库隔离层，通过模型上下文协议（MCP）将自然语言请求转换为已验证、优化且符合ACID的SQL，适用于生产级PostgreSQL集群的安全访问。

  • by Ismail-2001
  • TypeScript
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 Ismail-2001/mcp-server-postgres

使用说明

🚀 mcp服务器postgres

通过模型上下文协议（MCP）实现生产级、模式感知的PostgreSQL代理

mcp-server-postgres 是一个智能数据库隔离层，旨在弥合大型语言模型（LLM）和PostgreSQL生产集群之间的差距。它采用安全第一、模式感知的架构开发，将自然语言请求转换为经过验证、优化和ACID兼容的SQL。

🏗️ 技术架构

graph TD
    Client[MCP Client/LLM] -->|JSON-RPC| Server[MCP Server Hub]
    Server -->|Validation| Guard[Security Guardrails]
    Guard -->|AST/Pattern Scan| SQL[Validated SQL]
    SQL -->|Execution| Pool[Connection Pool Manager]
    Pool -->|Write Ops| Primary[Primary DB]
    Pool -->|Read Ops| Replica[Read Replicas]
    Pool -->|Auditing| Audit[Pino Structured Logs]

关键建筑支柱

  • 零信任安全管道：多阶段验证，包括“SELECT*”检测、强制模式限定和SQL注入预防。
  • 智能分页：透明的查询包装，以确保结果有界性（默认值：100行），而不会降低性能。
  • 动态模式反思：使LLM能够实时解析精确的表关系和索引。
  • 隔离层：实施严格的权限级别(READ_ONLY 到 ADMIN)维护最低特权原则。

🔒 安全护栏（不可协商）

  1. 规则-01：无无限制写入：拒绝任何 UPDATE 或 DELETE 缺少明确 WHERE 条款。
  2. 规则-04:DDL确认：高风险模式突变需要两步标记化确认流程。
  3. 掩码：对敏感列上PII编辑的原生支持（例如。， password_hash, ssn).
  4. 交易包装：所有多语句操作都在durable内部执行 BEGIN/COMMIT 阻碍。

🛠️ 配置

在中配置环境变量 .env:

变量 描述 默认值
DATABASE_URL 主PostgreSQL DSN 必需
READ_REPLICA_URL 用于读取路由的可选副本DSN null
PERMISSION_TIER READ_ONLY READ_WRITE
MASKED_COLUMNS 以逗号分隔的要编辑的列列表 null
MAX_ROWS 结果页面的硬上限 100
SLOW_QUERY_THRESHOLD_MS 延迟警告阈值 500

📋 工具集API

  • query(sql, params, page, page_size)：执行已验证的SQL。包括自动分页。
  • nl_query(request, context)：高级翻译接口（需要LLM桥）。
  • schema_inspect(schema, table)：对模式元数据进行深入反思。
  • list_tables(schema)：优化了当前数据库架构的枚举。
  • describe_table(schema, table)：列定义、索引和FK关系。
  • explain(sql, params)：具有成本估算功能的透明查询分析器。
  • transaction(operations)：复杂突变的原子批处理执行。
  • confirm_ddl(token)：已验证模式更改的最终执行。

🚦 入门指南

发展

npm install
npm run build
npm run start

与Claude Desktop集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-postgres/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/db",
        "PERMISSION_TIER": "READ_WRITE"
      }
    }
  }
}

📈 可观测性和测井

所有操作均通过以下方式记录 pino 企业可观察性。

{
  "level": "INFO",
  "module": "audit",
  "operation_type": "QUERY",
  "affected_tables": ["public.users"],
  "execution_ms": 12.4,
  "row_count": 8,
  "agent_identity": "mcp-server-postgres"
}

⚖️ 许可证

MIT许可证。由Ismail-2001精确创建。

相关 MCP