MCP Addon Postgresql Homeassistant

PostgreSQL MCP服务器家庭助理附加组件库

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

特性

• 🏠 家庭助理集成：使用家庭助理的身份验证系统
• 🗄️ PostgreSQL数据库访问：MCP工具的直接数据库连接
• 🔐 安全认证：验证Home Assistant API令牌
• 🛡️ SQL注入保护：内置查询验证和净化
• ⚙️ 写入操作控制：通过插件配置启用/禁用写入操作
• 🐳 Docker支持：打包为家庭助理插件
• ☁️ Cloudflare隧道就绪：设计用于与Home Assistant的cloudflare插件配合使用

安装

步骤1：将存储库添加到主助手

1. 首选 设置 > 附加组件 > 附加应用商店 在您的家庭助理中
2. 点击 ⋮ 右上角的（三点）菜单
3. 选择 仓库
4. 添加此存储库URL:

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

1. 点击 添加

步骤2：安装附加组件

1. 在插件商店中查找“PostgreSQL MCP服务器”
2. 点击它，然后点击 安装
3. 等待安装完成

步骤3：配置并启动

1. 转到 配置 标签
2. 使用PostgreSQL连接详细信息配置插件
3. 点击 保存
4. 转到 信息 选项卡并单击 开始

配置

插件配置

通过Home Assistant UI配置插件：

database_url: "postgresql://username:password@host:5432/database"
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：日志记录级别（调试、信息、警告、错误）
• MAX_CONNECTIONS：最大数据库连接数
• ENABLE_WRITE_OPERATIONS：启用写入操作（true/false）
• HA_BASE_URL：Home Assistant API基本URL（默认值：http://supervisor/core)

备注：身份验证是基于服务的，使用家庭助理的主管令牌。用户级访问控制不适用于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))"
    }
  }
}

认证

服务器使用家庭助理的身份验证系统。在授权标头中包含您的家庭助理长期访问令牌：

Authorization: Bearer YOUR_HOME_ASSISTANT_TOKEN

MCP客户端配置

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

本地访问：

# List available tools
curl -X POST http://your-ha-instance:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_HA_TOKEN" \
  -d '{"method": "tools/list"}'

# Call a tool
curl -X POST http://your-ha-instance:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_HA_TOKEN" \
  -d '{"method": "tools/call", "params": {"name": "listTables"}}'

Cloudflare隧道访问（HTTPS）：

# List available tools via Cloudflare tunnel
curl -X POST https://your-tunnel-domain.cloudflareaccess.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_HA_TOKEN" \
  -d '{"method": "tools/list"}'

# Call a tool via Cloudflare tunnel
curl -X POST https://your-tunnel-domain.cloudflareaccess.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_HA_TOKEN" \
  -d '{"method": "tools/call", "params": {"name": "listTables"}}'

与AI工具集成

MCP服务器可以与支持HTTP端点上的模型上下文协议的各种AI工具和平台集成。

通过SuperGateway集成Claude桌面

您可以通过以下方式将此MCP服务器与Claude Desktop一起使用 超级网关，它在基于HTTP的MCP服务器和Claude Desktop基于stdio的MCP客户端之间提供了一个桥梁。

安装说明：

1. 安装SuperGateway：

   npm install -g @supercorp-ai/supergateway

1. 配置Claude桌面：

将以下配置添加到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://your-ha-instance:3000/mcp",
           "--header", "Authorization: Bearer YOUR_HOME_ASSISTANT_TOKEN",
           "--header", "Content-Type: application/json"
         ]
       }
     }
   }

1. 对于Cloudflare隧道（HTTPS）访问：

   {
     "mcpServers": {
       "postgresql-ha": {
         "command": "supergateway",
         "args": [
           "--url", "https://your-tunnel-domain.cloudflareaccess.com/mcp",
           "--header", "Authorization: Bearer YOUR_HOME_ASSISTANT_TOKEN",
           "--header", "Content-Type: application/json"
         ]
       }
     }
   }

1. 重新启动克劳德桌面 加载新的MCP服务器配置。

Claude Desktop中的用法：

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

• *“列出数据库中的所有表”*
• *“显示用户表的架构”*
• *“查询数据库以查找所有活动用户”*
• *“创建用于存储产品信息的新表”* （如果启用了写入操作）

这种整合的好处：

• 🤖 自然语言接口：使用会话命令而不是JSON API调用
• 🔄 实时数据库访问：Claude可以直接查询和分析您的PostgreSQL数据
• 🛡️ 安全认证：所有请求都使用您的家庭助理令牌进行安全访问
• ☁️ 远程访问：适用于本地和Cloudflare隧道连接
• 📊 数据分析：Claude可以对数据库内容执行复杂的分析

对话示例：

You: "What tables are available in my database?"
Claude: [Uses listTables tool] "I can see you have the following tables: users, products, orders, and logs. Would you like me to examine the schema of any specific table?"

You: "Show me the structure of the users table"
Claude: [Uses queryDatabase tool] "The users table has columns: id (primary key), username, email, created_at, and is_active. There are currently 150 users in the table."

安全

SQL查询验证

该服务器包括为LLM生成的查询设计的基本SQL查询验证：

• 基于模式的验证 对于明显危险的构造（例如。， xp_cmdshell，格式错误的查询）
• 操作类型检测 区分读与写操作
• 多语句预防 阻止查询链接
• 基本语法验证 捕获格式错误的SQL

重要安全注意事项：

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

• 防止意外执行危险的行政命令
• 确保写入操作符合 enable_write_operations 设置
• 从LLM生成错误中捕获基本格式错误的查询

⚠️ 信任模型：此MCP服务器假定查询来自 可靠来源 （经过身份验证的AI助手，而不是不受信任的用户输入）。验证主要防止：

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

用于生产用途：

• 使用数据库级权限限制连接用户可以访问的内容
• 考虑将只读数据库副本用于仅查询操作
• 监控查询日志中的意外模式
• 实施网络级访问控制

访问控制

• 认证：所有请求都需要有效的家庭助理令牌
• 写入操作：由 enable_write_operations 插件设置
• 审计日志：所有数据库操作都记录在请求上下文中
• 连接限制：可配置的连接池

安全模型和信任假设

此MCP服务器专为 服务间通信 使用AI助手，而不是直接用户输入：

✅ 可信来源：

• 经过身份验证的AI助手（Claude、ChatGPT等）
• 拥有有效家庭助理令牌的MCP客户端
• 使用适当身份验证的自动化工具

❌ 不适合：

• 直接用户SQL输入，无需验证
• 面向公众的SQL接口
• 不受信任的第三方应用程序

推荐的安全措施：

1. 数据库权限：向PostgreSQL用户授予最低限度的必要权限
2. 网络安全：使用防火墙和VPN限制数据库访问
3. 监控：记录并监控所有数据库操作
4. 独立环境：将只读副本用于查询量大的操作
5. 定期更新：保持PostgreSQL和依赖项的更新

发展

先决条件

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

建筑

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Start the server
npm start

测试

# Build the addon
npm run build

# Test with curl
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_HA_TOKEN" \
  -d '{"method": "tools/list"}'

Cloudflare隧道集成

此插件旨在与Home Assistant的cloudflare插件配合使用，以实现安全的外部访问：

1. 安装和配置 家庭助理cloudflare插件
2. 配置隧道 暴露MCP服务器端口（3000）
3. 使用HTTPS URL 用于远程MCP客户端连接

Cloudflare隧道配置

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

# In your Cloudflare tunnel configuration
tunnel: your-tunnel-id
credentials-file: /etc/cloudflared/your-tunnel.json
ingress:
  - hostname: your-domain.cloudflareaccess.com
    service: http://localhost:3000
  - service: http_status:404

Cloudflare隧道的好处：

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

外部URL: https://your-tunnel-domain.cloudflareaccess.com/mcp

建筑

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │────│  Home Assistant │────│   PostgreSQL    │
│   (HTTP/HTTPS)  │    │   MCP Server    │    │    Database     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │
         │                        │                        │
    Local: HTTP           Home Assistant           Database
    Tunnel: HTTPS         Authentication              Pool
    via Cloudflare        Token Validation         Management

故障排除

常见问题

1. 连接被拒绝：检查插件是否正在运行以及端口是否可访问
2. 认证失败：验证家庭助理令牌是否有效
3. 数据库连接失败：检查PostgreSQL连接字符串
4. 写入操作已禁用：确保 enable_write_operations 设置为 true 如果需要执行写查询，请在插件配置中

日志

通过Home Assistant查看插件日志：

• 主管→ 附加组件→ PostgreSQL MCP服务器→ Logs

健康检查

服务器提供健康检查终结点：

curl http://localhost:3000/health

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

• GitHub问题： 创建问题
• 家庭助理社区： 论坛讨论

相关项目

• 模型上下文协议
• 家庭助手
• PostgreSQL
• Cloudflare 隧道