智能家居API规范

Hubitat Maker API-OpenAPI规范

OpenAPI 3.0规范 Hubitat 制造 API，设计用于与Workato MCP服务器、API网关和其他支持OpenAPI/Swagger规范的工具轻松集成。

概述

Hubitat Maker API提供了一个简单的HTTP接口，用于控制和监控连接到Hubitat Elevation集线器的智能家居设备。这个OpenAPI规范记录了所有可用的端点，使其易于：

• 导入到 计算机 为AI代理（Claude、ChatGPT、Cursor）创建MCP服务器
• 生成任何语言的API客户端
• 创建交互式API文档
• 构建与其他平台的集成

特性

本规范涵盖了Hubitat Maker API的所有功能：

快速开始

先决条件

1. Hubitat Elevation枢纽
2. 在您的集线器上安装并配置Maker API应用程序
3. 从Maker API实例访问令牌
4. Workato帐户（免费开发者沙盒可用）

获得免费的Workato开发者沙盒帐户

Workato提供了一个免费的开发者沙盒，可以完全访问他们的平台，包括MCP服务器功能。以下是如何开始：

1. 注册地址： workato.com/sandbox

   • 无需信用卡
   • 注册后立即访问

2. 内容包括：

   • 完全访问Workato ONE平台
   • 100000次免费使用活动（价值约1000美元）
   • 1200多个预制连接器
   • MCP服务器创建和托管
   • API平台访问
   • AI原生功能（AIRO副驾驶、智能文档处理）
   • 企业级安全（SAML 2.0、加密、审计日志）

3. 使用限制：

   • 无时间限制——访问将继续，直到达到使用限制
   • 达到限制时，食谱暂停，但您保留访问权限
   • 如果需要，可以选择升级计划

4. 支持的地区：

   • 美国、欧盟、非盟和新加坡数据中心
   • 托管在美国、欧盟和亚太地区的MCP服务器

💡 提示： 开发者沙盒是一个永久的开发者环境，而不是有时间限制的试用版。它专为实验和构建真正的集成而设计。

获取创客API凭据

1. 登录Hubitat中心的管理界面
2. 首选 应用程序 → 添加内置应用程序 → 制造商API
3. 选择要公开的设备
4. 注意你的 应用ID 和 访问令牌 从生成的URL

您的API URL格式为：

http://[HUB_IP]/apps/api/[APP_ID]/[endpoint]?access_token=[ACCESS_TOKEN]

使用Workato MCP

在Workato中创建MCP服务器

⚠️ 重要提示： 您必须启用 云访问 在Hubitat Maker API设置中，并使用云URL。Workato的服务器无法直接访问您的本地集线器IP。

步骤1：在Hubitat中启用云访问

1. 登录Hubitat中心的管理界面
2. 首选 应用程序 → 制造商API
3. 向下滚动并启用 允许通过云端点访问
4. 点击 完成 节省
5. 注意你的 云API URL --它看起来像：
   复制

   https://cloud.hubitat.com/api/YOUR_CLOUD_ID/apps/APP_ID
   

步骤2：在Workato中创建项目

1. 登录您的Workato帐户
2. 点击 项目 在侧边栏中
3. 点击 创建 → 项目
4. 输入名称（例如，“Hubitat智能家居”）
5. 点击 创建项目

步骤3：创建HTTP连接

1. 在项目内部，单击 创建 → 连接
2. 搜索并选择 超文本传输协议
3. 配置连接：
   • 连接名称： Hubitat 制造 API
   • 基本URL: 您的创客API 云 网址：
     复制

     https://cloud.hubitat.com/api/YOUR_CLOUD_ID/apps/APP_ID
     

   • 身份验证类型： 查询参数
   • 查询参数：
     • 密钥： access_token
     • 价值： 您的创客API访问令牌
4. 点击 连接 测试并保存

步骤4：创建API代理集合

1. 导航至 平台 → API平台 → API集合
2. 点击 创建新的API集合
3. 选择 API代理集合
4. 配置集合：
   • 姓名： Hubitat 制造 API
   • 版本： 第1版
   • 项目： 选择您的Hubitat项目
5. 选择 导入OpenAPI规范
6. 上传 hubitat-maker-api.yaml
7. 选择要公开的端点
8. 对于 HTTP连接，选择您在步骤3中创建的Hubitat连接
9. 点击 创建
10. 创建后，转到 端点 标签
11. 对于要使用的每个端点，单击 三点菜单 （⋮）并选择 激活 （或使用开关启用它们）

💡 提示： 您可以激活所有端点，也可以仅激活所需的端点。MCP服务器将无法使用非活动端点。

步骤5：创建MCP服务器

1. 首选 AI中心 → MCP服务器
2. 点击 创建MCP服务器
3. 姓名： Hubitat智能家居（或您喜欢的名字）
4. 选择工具： 选择您创建的Hubitat API集合
5. 点击 创建MCP服务器
6. 在MCP服务器页面上，单击 设置 标签
7. 在...之下 访问方法，确保 基于令牌的访问 被选中
8. 在...之下 开发人员MCP令牌，单击 复制 使用令牌复制完整URL
   • URL看起来像： https://406.apim.mcp.trial.workato.com/username/hubitat-maker-api-v1?wkt_token=...

💡 提示： 您还可以在上找到远程MCP URL（无令牌） 概述 右侧边栏中的选项卡。

示例：与Claude一起使用

配置MCP服务器后，您可以使用自然语言命令，如：

• “打开客厅的灯”
• “将卧室恒温器设置为72度”
• “我的所有设备的状态如何？”
• “把所有的门都锁上”
• “将房子设置为离开模式”

连接到AI助手

在Workato中创建MCP服务器后，您可以将其连接到各种AI助手。你需要你的 MCP网址 和 令牌 来自Workato：

1. 首选 AI中心 → MCP服务器
2. 点击您的Hubitat MCP服务器
3. 首选 设置 → 最终用户访问
4. 复制 开发人员MCP令牌 URL（包括 wkt_token)

克劳德（Claude.ai）

1. 打开 克劳德 并前往 设置 → 连接器
2. 点击 +添加新连接器
3. 输入连接器的名称（例如，“Hubitat智能家居”）
4. 将您的MCP URL和令牌粘贴到 远程MCP服务器URL 字段：
   复制

   https://XXX.apim.mcp.workato.com/your-username/hubitat-maker-api-v1?wkt_token=YOUR_TOKEN
   

5. 点击 添加
6. 点击 配置 关于新创建的连接器
7. 将权限设置为 始终征求许可 （推荐）或 允许无人监督
8. 开始新的聊天以使用您的Hubitat工具

ChatGPT（OpenAI）

1. 打开 ChatGPT 并前往 设置 → 应用程序和连接器
2. 启用 开发者模式 在...之下 高级设置
3. 回去 应用程序和连接器 然后单击 创建
4. 输入MCP连接器的名称（例如“Hubitat智能家居”）
5. 将您的MCP URL和令牌粘贴到 统一资源定位符 字段：
   复制

   https://XXX.apim.mcp.workato.com/your-username/hubitat-maker-api-v1?wkt_token=YOUR_TOKEN
   

6. 可选择添加描述
7. 集 认证 到 无身份验证 （身份验证通过URL中的令牌处理）
8. 选中复选框以接受添加自定义MCP服务器的风险
9. 点击 创建
10. 开始新的聊天以使用您的Hubitat工具

Claude桌面应用程序

对于Claude桌面应用程序，编辑配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json

添加您的MCP服务器配置：

{
  "mcpServers": {
    "hubitat": {
      "url": "https://XXX.apim.mcp.workato.com/your-username/hubitat-maker-api-v1?wkt_token=YOUR_TOKEN"
    }
  }
}

保存文件并重新启动Claude Desktop。

光标IDE

1. 首选 设置 → 光标设置
2. 点击 MCP和集成 在侧边栏中
3. 点击 +新建MCP服务器 打开 mcp.json 文件
4. 添加您的配置：

{
  "mcpServers": {
    "hubitat": {
      "url": "https://XXX.apim.mcp.workato.com/your-username/hubitat-maker-api-v1?wkt_token=YOUR_TOKEN"
    }
  }
}

5. 保存并与Cursor代理开始新的聊天

⚠️ 重要提示： 添加MCP服务器后，您必须开始新的聊天。AI助手仅在聊天开始时检测可用的MCP工具。

API端点参考

设备

设备命令

常用命令：

• on / off -开关控制
• lock / unlock -锁控制
• open / close -门/阀门控制
• setLevel/{0-100} -调光器级别
• setColorTemperature/{2700-6500} -色温（开尔文）
• setColor/{JSON} -使用HSB或十六进制值设置颜色
• setThermostatSetpoint/{temp} -恒温器控制
• refresh -刷新设备状态

中心变量

模式和HSM

HSM臂状态： armAway, armHome, armNight, disarm, disarmAll, cancelAlerts

配置

服务器URL

该规范包括两种服务器配置：

本地访问：

url: http://{hub_ip}/apps/api/{app_id}

云访问：

url: https://cloud.hubitat.com/api/{cloud_id}/apps/{app_id}

在导入之前，用您的特定值更新服务器变量。

认证

所有端点都需要 access_token 查询参数。在OpenAPI规范中，这被定义为：

securitySchemes:
  accessToken:
    type: apiKey
    in: query
    name: access_token

⚠️ 安全说明： 您的访问令牌类似于密码。任何拥有此令牌的人都可以控制您的设备。永远不要公开分享或将其提交给版本控制。

文件结构

├── README.md
├── hubitat-maker-api.yaml    # OpenAPI 3.0 specification
└── LICENSE

贡献

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

• 规范中的Bug修复
• 其他端点文档
• 集成示例
• 对描述的改进

资源

关闭

• Hubitat Maker API文档
• Hubitat社区论坛

计算机

• Workato开发人员沙盒注册
• Workato MCP文档
• Workato API集合指南
• MCP服务器入门
• 远程MCP服务器配置

开放API

• OpenAPI 3.0规范

许可证

MIT许可证-请参阅 许可证 了解详情。

免责声明

本项目不隶属于或认可Hubitat，股份有限公司。Hubitat和Hubitat Elevation是Hubitat公司的商标，股份有限公司。