麦克佩奇插件postgresql家庭助手

Name: 麦克佩奇插件postgresql家庭助手
Author: jodur

作者：jodur2 星标更新：2025-07-17

安装使用来源：spider==github.com

项目介绍

Home Assistant 插件仓库中的 PostgreSQL MCP 服务器

此仓库包含一个 Home Assistant 插件，该插件提供了一个用于 PostgreSQL 数据库访问的模型上下文协议（MCP）服务器，并通过 Home Assistant 的 API 令牌系统进行身份验证。

功能

🏠 Home Assistant 集成：使用 Home Assistant 的身份验证系统
🗄️ PostgreSQL 数据库访问：直接数据库连接供 MCP 工具使用
🔐 安全认证：验证 Home Assistant API 令牌
🛡️ SQL 注入防护：内置查询验证和清理
⚙️ 写操作控制：通过插件配置启用或禁用写操作
🐳 Docker 支持：作为 Home Assistant 插件打包
☁️ Cloudflare Tunnel 兼容：设计用于与 Home Assistant 的 Cloudflare 插件配合工作

安装

第一步：将仓库添加到 Home Assistant

在您的 Home Assistant 中前往设置 > 插件 > 插件商店
点击右上角的 ⋮ （三个点）菜单
选择仓库

添加此仓库 URL：

https://github.com/jodur/mcp-addon-postgresql-homeassistant

点击添加

第二步：安装插件

在插件商店中找到 "PostgreSQL MCP 服务器"
点击它并点击安装
等待安装完成

第三步：配置并启动

前往配置标签页
使用您的 PostgreSQL 连接详情配置插件
点击保存
前往信息标签页并点击启动

配置

插件配置

通过 Home Assistant UI 配置插件：

database_url: "postgresql://用户名:密码@主机:5432/数据库"
server_port: 3000
log_level: "info"
max_connections: 10
enable_write_operations: false
ha_base_url: "http://supervisor/core"  # Home Assistant API URL

环境变量

插件支持以下环境变量：

DATABASE_URL：PostgreSQL 连接字符串
SERVER_PORT：MCP 服务器端口（默认：3000）
LOG_LEVEL：日志级别（debug, info, warn, error）
MAX_CONNECTIONS：最大数据库连接数
ENABLE_WRITE_OPERATIONS：启用写操作（true/false）
HA_BASE_URL：Home Assistant API 基础 URL（默认：http://supervisor/core）

注意：认证基于服务，使用 Home Assistant 的监督器令牌。用户级别的访问控制不适用于 MCP 服务器，因为它们处理的是服务到服务的通信。

使用

可用的 MCP 工具

1. `listTables`

列出数据库中所有表及其模式信息。

{
  "method": "tools/call",
  "params": {
    "name": "listTables",
    "arguments": {
      "schema": "public"
    }
  }
}

2. `queryDatabase`

执行只读 SQL 查询。

{
  "method": "tools/call",
  "params": {
    "name": "queryDatabase",
    "arguments": {
      "sql": "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
    }
  }
}

3. `executeDatabase`

执行写操作（INSERT, UPDATE, DELETE, DDL）。仅在插件配置中将 enable_write_operations 设置为 true 时可用。

{
  "method": "tools/call",
  "params": {
    "name": "executeDatabase",
    "arguments": {
      "sql": "CREATE TABLE example (id SERIAL PRIMARY KEY, name VARCHAR(100))"
    }
  }
}

认证

服务器使用 Home Assistant 的认证系统。在 Authorization 头中包含您的 Home Assistant 长期访问令牌：

Authorization: Bearer 您的HOME_ASSISTANT_TOKEN

MCP 客户端配置

对于基于 HTTP 的 MCP 客户端，使用 REST API 端点：

本地访问：

# 列出可用工具
curl -X POST http://您的HA实例:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 您的HA_TOKEN" \
  -d '{"method": "tools/list"}'

# 调用一个工具
curl -X POST http://您的HA实例:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 您的HA_TOKEN" \
  -d '{"method": "tools/call", "params": {"name": "listTables"}}'

Cloudflare Tunnel 访问（HTTPS）：

# 通过 Cloudflare tunnel 列出可用工具
curl -X POST https://您的隧道域名.cloudflareaccess.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 您的HA_TOKEN" \
  -d '{"method": "tools/list"}'

# 通过 Cloudflare tunnel 调用一个工具
curl -X POST https://您的隧道域名.cloudflareaccess.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 您的HA_TOKEN" \
  -d '{"method": "tools/call", "params": {"name": "listTables"}}'

与 AI 工具集成

MCP 服务器可以与支持 HTTP 端点上的 Model Context Protocol 的各种 AI 工具和平台集成。

通过 SuperGateway 与 Claude Desktop 集成

您可以使用此 MCP 服务器与 Claude Desktop 通过 SuperGateway 集成，它提供了 HTTP 基础 MCP 服务器与 Claude Desktop 的 stdio 基础 MCP 客户端之间的桥梁。

设置说明：

安装 SuperGateway：

npm install -g @supercorp-ai/supergateway

配置 Claude Desktop： 将以下配置添加到您的 Claude Desktop MCP 设置文件中：

在 macOS 上： ~/Library/Application Support/Claude/claude_desktop_config.json 在 Windows 上： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "postgresql-ha": {
      "command": "supergateway",
      "args": [
        "--url", "http://您的HA实例:3000/mcp",
        "--header", "Authorization: Bearer 您的HOME_ASSISTANT_TOKEN",
        "--header", "Content-Type: application/json"
      ]
    }
  }
}

对于 Cloudflare Tunnel（HTTPS）访问：

{
  "mcpServers": {
    "postgresql-ha": {
      "command": "supergateway",
      "args": [
        "--url", "https://您的隧道域名.cloudflareaccess.com/mcp",
        "--header", "Authorization: Bearer 您的HOME_ASSISTANT_TOKEN",
        "--header", "Content-Type: application/json"
      ]
    }
  }
}

重启 Claude Desktop 以加载新的 MCP 服务器配置。

在 Claude Desktop 中的使用：

一旦配置好，您可以在 Claude Desktop 中使用自然语言命令，例如：

"列出数据库中的所有表"
"显示用户表的结构"
"查询数据库以查找所有活跃用户"
"创建一个新的表来存储产品信息"（如果启用了写操作）

此集成的好处：

🤖 自然语言界面：使用对话命令而不是 JSON API 调用
🔄 实时数据库访问：Claude 可以直接查询和分析您的 PostgreSQL 数据
🛡️ 安全认证：所有请求都使用您的 Home Assistant 令牌进行安全访问
☁️ 远程访问：同时支持本地和 Cloudflare tunnel 连接
📊 数据分析：Claude 可以对数据库内容进行复杂分析

示例对话：

您： "我的数据库中有哪些表？"
Claude： [使用 listTables 工具] "我可以看到您有以下表：users, products, orders 和 logs。您想让我检查任何特定表的模式吗？"

您： "显示用户表的结构"
Claude： [使用 queryDatabase 工具] "用户表有列：id（主键），username，email，created_at 和 is_active。目前表中有 150 名用户。"

安全性

SQL 查询验证

服务器包括基本的 SQL 查询验证，旨在针对 LLM 生成的查询：

基于模式的验证，用于明显危险的构造（如 xp_cmdshell，畸形查询）
操作类型检测，区分读取和写入操作
多语句预防，阻止查询链
基本语法验证，捕获畸形 SQL

重要安全注意事项：

⚠️ 这不是全面的 SQL 注入保护。 验证旨在：

防止意外执行危险的管理命令
确保写操作尊重 enable_write_operations 设置
捕获来自 LLM 生成错误的基本畸形查询

⚠️ 信任模型：此 MCP 服务器假设查询来自 可信来源（认证的 AI 助手，而非未经验证的用户输入）。验证主要防止：

意外破坏性操作
LLM 幻觉生成危险 SQL 模式
配置错误（当禁用时执行写操作）

生产使用建议：

使用数据库级别的权限限制连接用户可以访问的内容
考虑使用只读数据库副本进行查询操作
监控查询日志以发现异常模式
实现网络级别的访问控制

访问控制

认证：所有请求都需要有效的 Home Assistant 令牌
写操作：由插件设置 enable_write_operations 控制
审计日志：所有数据库操作均带有请求上下文记录
连接限制：可配置的连接池

安全模型及信任假设

此 MCP 服务器设计用于 AI 助手之间的服务到服务通信，而非直接用户输入：

✅ 可信来源：

认证的 AI 助手（Claude，ChatGPT 等）
具有有效 Home Assistant 令牌的 MCP 客户端
使用适当认证的自动化工具

❌ 不适合：

未经验证的用户 SQL 输入
对公众开放的 SQL 接口
不可信的第三方应用程序

推荐的安全实践：

数据库权限：授予 PostgreSQL 用户最小必要的权限
网络安全：使用防火墙和 VPN 限制数据库访问
监控：记录并监控所有数据库操作
分离环境：使用只读副本进行查询密集型操作
定期更新：保持 PostgreSQL 和依赖项的更新

开发

前提条件

Node.js 18+
TypeScript
Docker（用于插件打包）
Home Assistant 开发环境

构建

# 安装依赖
npm install

# 构建 TypeScript
npm run build

# 在开发模式下运行
npm run dev

# 启动服务器
npm start

测试

# 构建插件
npm run build

# 使用 curl 测试
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 您的HA_TOKEN" \
  -d '{"method": "tools/list"}'

Cloudflare Tunnel 集成

此插件设计用于与 Home Assistant 的 Cloudflare 插件配合工作，以实现安全的外部访问：

安装并配置 Home Assistant 的 Cloudflare 插件
配置隧道 以暴露 MCP 服务器端口（3000）
使用 HTTPS URL 进行远程 MCP 客户端连接

Cloudflare Tunnel 配置

使用 Cloudflare tunnel 时，您的 MCP 服务器可通过 HTTPS 访问：

# 在您的 Cloudflare tunnel 配置中
tunnel: 您的隧道ID
credentials-file: /etc/cloudflared/您的隧道.json
ingress:
  - hostname: 您的域名.cloudflareaccess.com
    service: http://localhost:3000
  - service: http_status:404

Cloudflare Tunnel 的好处：

HTTPS 加密 - 所有流量自动加密
全球 CDN - 从世界任何地方快速访问
DDoS 防护 - 内置攻击防护
访问控制 - 可选的 Cloudflare Access 集成
无需端口转发 - 不需要打开防火墙端口

外部 URL：https://您的隧道域名.cloudflareaccess.com/mcp

架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP 客户端    │────│  Home Assistant │────│   PostgreSQL    │
│   (HTTP/HTTPS)  │    │   MCP 服务器    │    │    数据库       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │
         │                        │                        │
    本地：HTTP           Home Assistant           数据库
    隧道：HTTPS         认证                   管理
    通过 Cloudflare    令牌验证             连接池

故障排除

常见问题

连接被拒绝：检查插件是否正在运行且端口可访问
认证失败：验证 Home Assistant 令牌是否有效
数据库连接失败：检查 PostgreSQL 连接字符串
写操作已禁用：确保插件配置中 enable_write_operations 设置为 true 如果需要执行写查询

日志

通过 Home Assistant 查看插件日志：

监督器 → 插件 → PostgreSQL MCP 服务器 → 日志

健康检查

服务器提供健康检查端点：

curl http://localhost:3000/health

贡献

分叉仓库
创建功能分支
进行更改
如适用，添加测试
提交拉取请求

许可

MIT 许可 - 详情见 LICENSE 文件。

支持

对于问题和疑问：

GitHub Issues：创建一个问题
Home Assistant 社区：论坛讨论