Pg Lens MCP

PG镜头MCP服务器

将AI助手安全地连接到PostgreSQL数据库

特性 • 安装 • 配置 • 工具 • 安全

______________________________________________________________________

✨ 特性

______________________________________________________________________

🏗️ 建筑

graph LR
    A[Claude/AI Assistant] -->|MCP Protocol| B[PostgreSQL MCP Server]
    B -->|READ ONLY Transactions| C[(PostgreSQL Database)]
    
    style B fill:#4CAF50,color:#fff
    style C fill:#336791,color:#fff

服务器充当AI助手和PostgreSQL数据库之间的安全桥梁，在数据库事务级别强制执行只读访问。

______________________________________________________________________

📦 安装

git clone https://github.com/YohannHommet/pg-lens-mcp.git
cd pg-lens-mcp
npm install
npm run build

______________________________________________________________________

⚙️ 配置

环境变量

使用环境变量配置连接：

MCP配置

添加到您的Claude桌面配置(~/.claude/claude_desktop_config.json):

选项1：直接Node.js（本地安装）

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/absolute/path/to/postgres-server/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_SCHEMA": "public"
      }
    }
  }
}

选项2：使用npx（无需安装）

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "pg-lens-mcp"
      ],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_SCHEMA": "public"
      }
    }
  }
}

选项3：使用Docker

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=host",
        "-e", "DB_HOST=localhost",
        "-e", "DB_PORT=5432",
        "-e", "DB_DATABASE=your_database",
        "-e", "DB_USERNAME=your_username",
        "-e", "DB_PASSWORD=your_password",
        "-e", "DB_SCHEMA=public",
        "pg-lens-mcp:latest"
      ]
    }
  }
}

Docker特定注意事项：

• 使用 --network=host 用于连接到本地主机数据库
• 对于远程数据库，您可以删除 --network=host
• 对于其他Docker容器中的数据库，请使用自定义网络：

  "args": [
    "run", "--rm", "-i",
    "--network=your_docker_network",
    "-e", "DB_HOST=postgres_container_name",
    ...
  ]

💡 提示： 使用只读数据库用户以获得额外的安全性，即使所有查询都在只读事务中运行。

______________________________________________________________________

🛠️ 可用工具

🗂️ 架构发现

list_schemas — List all non-system schemas

发现数据库中所有用户定义的模式。

示例用法：

"List all schemas in the database"

退货： 带有模式名称和所有者的Markdown表

list_tables — List all tables in a schema

参数：

• schema *（可选）* --架构名称（默认值： public)

示例用法：

"Show me all tables in the public schema"

退货： 带表名和类型的Markdown表（table、VIEW等）

search_column — Find tables containing a column pattern

参数：

• column_pattern *（必填）* --部分或完整列名（不区分大小写）

示例用法：

"Find all tables that have an 'email' column"

退货： 显示模式、表、列名、数据类型和可空性的Markdown表

get_table_info — Get comprehensive table schema

参数：

• table_name *（必填）* --要检查的表的名称
• schema *（可选）* --架构名称（默认值： public)

示例用法：

"Show me the complete structure of the users table"

退货： JSON格式：

• 列详细信息（名称、类型、可空性、默认值）
• 主键
• 外键关系
• 具有唯一性信息的索引

______________________________________________________________________

📊 数据查询

get_table_data — Query table data with structured filters

参数：

• table_name *（必填）* --要查询的表
• schema *（可选）* --架构名称（默认值： public)
• columns *（可选）* --要选择的特定列（默认：全部）
• filters *（可选）* — 结构化过滤器 （SQL注入安全！）

  [{
    column: "status",
    operator: "=",  // Options: =, !=, , =, LIKE, ILIKE, IN, IS NULL, IS NOT NULL
    value: "active"
  }]

• limit *（可选）* --要返回的最大行数（默认值：100，最大值：1000）
• offset *（可选）* --分页时要跳过的行
• order_by *（可选）* --排序依据的列
• order_direction *（可选）* — ASC 或 DESC （默认值： ASC)

示例用法：

"Get the first 20 active users created after 2024-01-01, ordered by creation date"

退货： Markdown表格包含：

• 查询结果
• 元数据（总行数、返回行数、分页信息）

execute_query — Execute custom read-only SQL

参数：

• query *（必填）* --SQL SELECT查询
• params *（可选）* --查询参数 $1, $2等等。

示例用法：

"Execute this query: 
SELECT u.name, COUNT(o.id) as order_count 
FROM users u 
LEFT JOIN orders o ON u.id = o.user_id 
GROUP BY u.name 
ORDER BY order_count DESC 
LIMIT 10"

退货： 带查询结果的Markdown表

安全： 跑步 BEGIN TRANSACTION READ ONLY --PostgreSQL本身强制禁止写入

______________________________________________________________________

⚡ 性能分析

explain_query — Get query execution plan (without running query)

参数：

• query *（必填）* --要分析的SQL查询
• format *（可选）* — text, json，或 yaml （默认值： json)
• verbose *（可选）* --包含详细信息（默认值： false)

示例用法：

"Explain how PostgreSQL would execute: SELECT * FROM users WHERE email LIKE '%@example.com'"

退货： 查询执行计划，显示：

• 扫描类型（顺序扫描、索引扫描等）
• 估计成本和行数
• 加盟策略

使用案例： 优化前了解查询性能

explain_analyze — Execute and profile query performance

参数：

• query *（必填）* --要分析的SQL查询
• format *（可选）* — text 或 json （默认值： json)
• buffers *（可选）* --包括缓冲区使用统计数据（默认值： false)
• timing *（可选）* --包括计时信息（默认值： true)
• verbose *（可选）* --详细输出（默认值： false)

示例用法：

"Analyze the actual performance of: SELECT * FROM large_table WHERE indexed_column = 'value'"

退货： 实际执行统计数据包括：

• 实时执行时间
• 实际处理行与估计行
• 缓冲区命中/未命中（如果 buffers: true)
• 节点级时序分解

⚠️ 注： 这实际上执行了查询（在只读模式下）。在大型数据集上可能很慢。

______________________________________________________________________

🔐 安全

数据库强制只读访问

与简单的关键字过滤不同，此服务器使用 PostgreSQL的事务性只读模式:

await client.query('BEGIN TRANSACTION READ ONLY');
const result = await client.query(userQuery);  // ← PostgreSQL blocks ANY writes
await client.query('COMMIT');

为什么这很重要：

✅ 无误报 --在字符串/注释中包含“UPDATE”或“INSERT”等单词的查询工作正常\ ✅ 无旁路 --无法通过存储过程、函数或扩展来规避\ ✅ 数据库级保证 --PostgreSQL本身强制执行只读约束

SQL注入保护

结构化过滤器 替换危险的字符串连接：

❌ 不安全的方法：

query += ` WHERE ${userInput}`  // Direct concatenation = SQL injection risk

✅ 我们的方法：

filters: [{
  column: "status",
  operator: "=",
  value: "active"
}]
// Becomes: WHERE "status" = $1 
// PostgreSQL handles escaping automatically

所有用户输入都已正确参数化，消除了SQL注入向量。

______________________________________________________________________

🧪 测试服务器

快速测试

# Set your database credentials
export DB_HOST=localhost
export DB_DATABASE=your_database
export DB_USERNAME=your_username
export DB_PASSWORD=your_password

# Start the server
node dist/index.js

预期产量：

✓ Database connection verified
✓ PostgreSQL MCP Server running on stdio

使用Claude Desktop进行测试

1. 将服务器添加到MCP配置中
2. 重新启动克劳德桌面
3. 尝试以下示例提示：

- “列出数据库中的所有架构” - “显示用户表的结构” - “查找所有具有'created_at'列的表” - “解释SELECT\*FROM large_table LIMIT 10的查询计划”

______________________________________________________________________

📋 故障排除

连接问题

“密码验证失败”

• 检查 DB_USERNAME 和 DB_PASSWORD 是正确的
• 验证用户是否有权访问指定的数据库

“连接超时”

• 检查 DB_HOST 可以联系到
• 验证PostgreSQL是否正在运行 DB_PORT
• 如果远程连接，请检查防火墙规则

“数据库不存在”

• 验证 DB_DATABASE 名称正确
• 列出可用数据库： psql -l

演出

如果查询速度较慢：

1. 使用 explain_analyze 识别瓶颈的工具
2. 检查频繁查询的列上是否存在索引
3. 考虑调整 DB_MAX_CONNECTIONS 根据您的工作量

______________________________________________________________________

📄 许可证

MIT许可证

______________________________________________________________________

🤝 贡献

欢迎投稿！请随时提交问题或拉取请求。

______________________________________________________________________

为模型上下文协议生态系统构建

由...制作❤️ 用于人工智能辅助数据库探索