Postgre MCP

PostgreSQL MCP服务器-AI代理数据库访问

通过模型上下文协议（MCP）将人工智能代理（如Claude、ChatGPT和其他LLM驱动的工具）连接到PostgreSQL数据库。此Apify Actor实现了一个生产就绪的MCP服务器，该服务器支持智能数据查询、探索和分析，同时保持强大的安全控制。

这个演员做什么

该Actor通过实现模型上下文协议（MCP）弥合了AI代理和PostgreSQL数据库之间的差距，MCP是将AI助手连接到外部数据源的开放标准。配置后，AI代理可以：

• 执行SQL查询以检索和分析数据
• 发现数据库模式和表结构
• 探索表关系和约束
• 通过自然语言从数据中生成见解

Actor的设计将安全性作为首要任务，提供只读模式、查询超时、行限制和模式限制，以确保安全的人工智能数据库访问。

为什么要使用这个演员？

用你的数据赋能人工智能：当人工智能代理可以直接访问您的运营数据时，他们可以提供更有价值的见解。此Actor使连接安全而简单。

生产就绪安全：内置的保护措施可防止未经授权的数据修改，限制资源使用，并限制对特定数据库模式的访问。

通用兼容性：适用于任何PostgreSQL数据库（包括AWS RDS、Google Cloud SQL、Azure数据库和自托管实例）和任何兼容MCP的AI代理。

综合录井：每个查询都会记录到Apify的数据集存储中，提供所有AI数据库交互的完整审计跟踪。

零基础设施：在Apify的托管平台上运行-无需维护服务器，无需担心扩展问题，无需部署复杂性。

特性

核心能力

• SQL查询执行：执行具有自动结果格式的任意SQL查询
• 表发现：使用元数据列出允许的架构中的所有表
• 图式反思：获取详细的列信息、数据类型和约束
• 数据采样：预览具有可配置行限制的表内容
• 连接池：高效的连接管理，实现高性能查询

安全功能

• 只读模式：强制执行仅SELECT查询，防止INSERT、UPDATE、DELETE和DDL操作
• 架构限制：限制AI对特定数据库模式的访问
• 查询超时：自动终止长时间运行的查询
• 行限制：限制返回的最大行数以防止内存耗尽
• SQL注入保护：参数化查询和标识符转义
• SSL/TLS支持：保护与数据库的加密连接

MCP协议合规性

• 全面实施MCP工具规范
• 用于可靠通信的标准传输
• 结构化错误处理和报告
• 适当的工具元数据和文档

输入参数

连接字符串格式

PostgreSQL连接字符串应遵循以下格式：

postgresql://username:password@hostname:port/database_name

示例：

• 本地数据库： postgresql://postgres:mypassword@localhost:5432/myapp
• 云数据库： postgresql://admin:secure_pass@db.example.com:5432/production
• 使用SSL： postgresql://user:pass@host:5432/db?sslmode=require

可用的MCP工具

Actor公开了AI代理可以调用的四个MCP工具：

1.查询

对数据库执行SQL查询。尊重所有安全设置，包括只读模式、查询超时和行限制。

参数：

• query （string，必填）：要执行的SQL查询

例子：

SELECT customer_name, email, total_orders 
FROM customers 
WHERE country = 'USA' 
ORDER BY total_orders DESC 
LIMIT 10

2.列表表

列出数据库中的所有表，按允许的模式进行筛选。返回包含行数和大小的元数据的表名。

参数：

• schema （字符串，可选）：按特定架构筛选表

退货： 一系列表格 schema, tableName, rowCount，以及 tableSize 领域。

3.描述表

获取特定表的全面架构信息，包括列、数据类型、约束、索引和外键关系。

参数：

• schema （string，必填）：包含表的架构
• table （字符串，必填）：要描述的表名

退货： 完整的表描述，包括列、约束、索引和外键。

4.获取表样本

从表中检索示例行以进行数据预览和探索。

参数：

• schema （string，必填）：包含表的架构
• table （字符串，必填）：要采样的表名
• limit （整数，可选）：要返回的行数（默认值：10，最大值： maxQueryResults)

退货： 表中的示例行数组。

用例

1.RAG（检索增强生成）

AI代理可以查询您的生产数据库，以检索实时数据来回答问题。代理访问当前信息，而不是依赖静态训练数据。

例子： “上个月我们收入排名前五的产品是什么？”-人工智能会查询您的销售数据库，并提供准确、最新的答案。

2.数据分析和商业智能

将Claude或ChatGPT连接到您的分析数据库，并用自然语言提出复杂的分析问题。AI将您的问题转换为SQL并解释结果。

例子： “按订阅级别细分，向我展示过去一年的客户流失率趋势。”

3.自动报告

AI代理可以通过查询数据库、分析模式和创建叙述性摘要来生成自定义报告，而无需手动编写SQL。

例子： “创建一份所有地区第四季度绩效的总结报告，突出显示显著的变化。”

4.数据库探索和文档

新团队成员可以向AI助手询问您的数据库模式、关系和数据模式，以便更快地理解系统。

例子： “哪些表存储客户信息，它们之间有什么关系？”

运作原理

建筑

┌─────────────────┐         MCP Protocol (stdio)         ┌──────────────────┐
│   AI Agent      │◄──────────────────────────────────────►│  Apify Actor     │
│ (Claude/ChatGPT)│         Tool Calls & Responses        │   MCP Server     │
└─────────────────┘                                       └─────────┬────────┘
                                                                    │
                                                          PostgreSQL Connection
                                                                    │
                                                                    ▼
                                                          ┌──────────────────┐
                                                          │   PostgreSQL     │
                                                          │    Database      │
                                                          └──────────────────┘

执行流程

1. 初始化：Actor启动、验证输入并建立数据库连接
2. 连接测试：在启动MCP服务器之前验证数据库连接
3. MCP服务器启动：开始监听stdio上的工具调用（标准输入/输出）
4. 刀具加工：接收来自AI代理的工具调用，执行数据库操作
5. 结果格式：将查询结果格式化为JSON并返回给AI代理
6. 日志记录：将所有操作记录到Apify数据集以供审计和监控
7. 优雅关闭：Actor终止时关闭数据库连接

集成示例

Claude桌面配置

将此配置添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "postgresql": {
      "command": "apify",
      "args": ["call", "your-username/postgresql-mcp-server", "--input", "@config.json"]
    }
  }
}

创建 config.json 使用您的数据库连接：

{
  "connectionString": "postgresql://user:password@host:port/database",
  "allowedSchemas": ["public", "analytics"],
  "readOnly": true,
  "maxQueryResults": 1000,
  "timeout": 30
}

AI代理的示例查询

连接后，您可以向您的AI代理提出自然语言问题：

• “数据库中有哪些表可用？”
• “显示用户表的架构”
• “从订单表中获取5行示例”
• “我们在美国有多少活跃客户？”
• “过去30天的平均订单价值是多少？”

AI将自动使用适当的MCP工具(list_tables, describe_table, get_table_sample, query)回答你的问题。

安全注意事项

只读模式（强烈推荐）

始终使用 readOnly: true 除非您有特定的数据修改需求。这可以防止：

• 意外删除或修改数据
• 插入/更新/删除操作
• 架构更改（CREATE、ALTER、DROP）
• 特权修改（授予、撤销）

只读模式下只允许SELECT和EXPLAIN查询。

架构限制

限制 allowedSchemas 只访问您的AI代理需要访问的模式。这提供了深度防御：

• 阻止访问系统表
• 在受限模式中隔离敏感数据
• 启用多租户数据库共享

查询限制和超时

配置适当 maxQueryResults 和 timeout 值：

• 防止大型结果集导致内存耗尽
• 阻止可能影响数据库性能的失控查询
• 防止意外的全表扫描

连接安全性

使用 sslMode: "require" 通过互联网连接时：

• 加密传输中的数据
• 防止中间人攻击
• 需要符合许多安全标准

凭证管理

安全地存储数据库凭据：

• 对敏感连接字符串使用Apify机密输入
• 从不将凭据提交到版本控制
• 定期轮换凭据
• 尽可能使用只读数据库用户

审计日志

所有查询都记录到Apify数据集：

• 定期查看查询日志以查找可疑活动
• 监视意外查询模式
• 跟踪哪些工具使用最频繁

输出格式

Actor将所有操作记录到Apify数据集。每个条目包括：

{
  "tool": "query",
  "query": "SELECT * FROM customers WHERE country = 'USA' LIMIT 10",
  "timestamp": "2025-12-03T10:30:45.123Z",
  "executionTime": 145,
  "rowsReturned": 10,
  "success": true
}

领域：

• tool：所调用的MCP工具的名称（查询、list_tables、describe_table、get_table_sample）
• query：已执行SQL查询（仅适用于查询工具）
• parameters：工具参数（用于非查询工具）
• timestamp：ISO 8601时间戳
• executionTime：持续时间（毫秒）
• rowsReturned：返回的行数
• success：表示成功或失败的布尔值
• error：错误消息（仅在以下情况下出现 success: false)

通过Apify控制台或API访问数据集，以分析查询模式和性能。

常见问题及排除方法

连接失败

问题：“数据库连接失败：连接被拒绝”

解决：

• 验证连接字符串是否正确
• 检查数据库服务器是否正在运行
• 确保防火墙允许来自Apify IP地址的连接
• 验证用户名和密码是否正确

SSL/TLS错误

问题：“SSL连接错误：自签名证书”

解决：

• 使用 sslMode: "prefer" 而不是 "require" 用于自签名证书
• 将正确的SSL证书添加到数据库服务器
• 为了开发，使用 sslMode: "disable" （不建议用于生产）

查询超时

问题：“查询超时：执行时间超过30秒”

解决：

• 使用适当的索引优化查询
• 增加 timeout 参数
• 使用更具体的WHERE子句来减少扫描的数据
• 考虑将复杂的查询具体化到汇总表中

只读模式错误

问题：“只读模式：不允许INSERT操作”

解决：

• 这是在以下情况下的预期行为 readOnly: true
• 集 readOnly: false 如果您需要修改数据（请谨慎使用）
• 验证您的查询实际上是SELECT语句
• 检查是否包含修改的CTE（WITH条款）

架构访问被拒绝

问题：“架构‘private’不在允许的架构列表中”

解决：

• 将架构添加到 allowedSchemas 数组
• 验证架构名称拼写是否正确（区分大小写）
• 列出可用架构，包括： SELECT schema_name FROM information_schema.schemata

开发和测试

局部测试

1. 安装依赖项：

npm install

1. 构建TypeScript：

npm run build

1. 创建测试输入文件 input.json:

{
  "connectionString": "postgresql://localhost:5432/testdb",
  "readOnly": true
}

1. 在本地运行：

node dist/main.js

MCP检验员测试

使用MCP检查器工具测试您的服务器：

npx @modelcontextprotocol/inspector dist/main.js

这将打开一个web界面，您可以在其中交互式地测试工具调用。

技术细节

语言：TypeScript（编译为JavaScript） 节点版本: 20+ MCP-SDK：@modelcontextprotocol/sdk^0.5.0 数据库驱动：pg（节点后缀）^8.11.3 平台：Apify Actor（基于Docker）

支持和贡献

有关问题、功能请求或贡献，请访问 .

许可证

MIT许可证-您可以在项目中自由使用此Actor，对其进行修改和重新分发。

______________________________________________________________________

专为Apify 100万美元挑战赛打造 -通过模型上下文协议赋予AI代理安全的数据库访问权限。