AI导哈

PostgreSQL数据库连接服务

PG Lens MCP Server是一款安全连接AI助手与PostgreSQL数据库的服务，提供只读访问、模式发现、查询性能分析等功能。

  • by YohannHommet
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 YohannHommet/pg-lens-mcp

使用说明

PG镜头MCP服务器

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

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

✨ 特性

特性 描述
按设计只读 所有查询都在数据库强制的只读事务中执行
完整架构发现 探索模式、表、列、索引和关系
查询性能分析 内置EXPLAIN和EXPLAIN ANALYZE进行优化
SQL注入安全 具有参数化查询的结构化过滤器
令牌优化输出 Markdown表格格式将AI令牌的使用率降低了约40-60%
8强大的工具 数据库探索和分析的完整工具包
生产就绪 具有超时和健康检查功能的可配置连接池

🏗️ 建筑

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

⚙️ 配置

环境变量

使用环境变量配置连接：

变量 描述 默认值
DB_HOST PostgreSQL主机 localhost
DB_PORT PostgreSQL端口 5432
DB_DATABASE 数据库名称 postgres
DB_USERNAME 数据库用户 postgres
DB_PASSWORD 数据库密码 postgres
DB_SCHEMA 默认架构 public
DB_MAX_CONNECTIONS 连接池大小 10
DB_IDLE_TIMEOUT_MS 空闲连接超时 30000
DB_CONNECTION_TIMEOUT_MS 连接尝试超时 5000

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许可证

🤝 贡献

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

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

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

相关 MCP