AI导哈

智能家居控制协议服务

一个为Home Assistant构建的MCP服务器，通过流式HTTP传输将智能家居功能暴露为MCP工具，使AI助手能够与智能家居互动。

  • by Mozart409
  • Rust
  • 本地部署
  • 更新于
在 GitHub 查看 Mozart409/hamcp-rs

使用说明

hamcp-rs

MCP(模型上下文协议)服务器 家庭助手 内置于Rust中。

通过流式HTTP传输将家庭助理功能作为MCP工具公开， 允许AI助手与您的智能家居进行交互。

工具

工具 说明
health_check 验证是否可以访问Home Assistant API
get_config 获取家庭助理配置
get_states 获取所有实体状态
get_entity 获取特定实体的状态
call_service 呼叫家庭助理服务
set_state 设置或更新实体状态
get_services 获取所有可用服务
render_template 渲染家庭助手模板
get_calendars 获取所有日历实体
get_calendar_events 从日历中获取事件
check_config 验证家庭助理配置
get_history 获取历史状态数据

先决条件

快速开始

使用Nix（推荐）

# Run directly without installing
nix run github:youruser/hamcp-rs

# Or build it
nix build github:youruser/hamcp-rs
./result/bin/mcp

来源

# Enter the dev shell (provides Rust nightly + all tooling)
nix develop

# Build and run
cargo build --release
./target/release/mcp

环境变量

变量 必填 默认 描述
HA_URL 是 -- 家庭助理实例URL（例如。 http://homeassistant:8123)
HA_TOKEN 是 -- 长期访问令牌
MCP_ADDR 没有 0.0.0.0:3000 服务器绑定地址和端口

复制 .env.example 到 .env 地方发展：

cp .env.example .env
# Edit .env with your values

部署

NixOS / 科尔梅纳

薄片在以下位置导出NixOS模块 nixosModules.default 这创建了一个硬化的系统d 服务态度 DynamicUser, LoadCredential （令牌从不进入Nix商店），并且已满 安全沙盒。

在部署中添加hamcp-rs作为flake输入：

{
  inputs.hamcp.url = "github:mozart409/hamcp-rs";

  outputs = { hamcp, ... }: {
    colmena = {
      your-vm = {
        imports = [ hamcp.nixosModules.default ];

        services.hamcp = {
          enable = true;
          haUrl = "http://homeassistant.local:8123";
          haTokenFile = config.sops.secrets.ha-token.path; # or agenix
          port = 3000;
          openFirewall = true;
        };
      };
    };
  };
}

模块选项

选项 类型 默认值 描述
enable bool的。 false 启用hamcp服务
package 包装 self.packages 要使用的hamcp包
haUrl str （必填） 家庭助理实例URL
haTokenFile path （必需） 包含HA访问令牌的文件的路径
port 港口 3000 监听端口
address str "0.0.0.0" 绑定地址
openFirewall bool的。 false 打开NixOS防火墙中的端口

这 haTokenFile 应仅包含原始令牌字符串。它在运行时通过以下方式加载 系统守护进程 LoadCredential，因此它适用于sops-nix、agenix或任何基于文件的秘密管理器。

连接MCP客户端

一旦运行，服务器就会监听 http://<address>:<port>/mcp 使用流式HTTP传输。

将MCP客户端指向端点：

http://your-server:3000/mcp

MCP检验员测试

npx @modelcontextprotocol/inspector http://localhost:3000/mcp

发展

# Enter the Nix dev shell
nix develop

# Run checks
cargo check
cargo clippy
cargo test

# Run the server in dev mode
cargo run --bin mcp

# Watch mode with bacon
bacon          # check
bacon clippy   # lint
bacon test     # test
bacon run      # run

# Run all pre-commit checks
lefthook run pre-commit

Nix构建

薄片使用 起重机 带有锈层。起重机缓存 依赖关系是单独构建的，因此增量重建很快。

# Build the binary
nix build .#mcp

# Run without building
nix run .#mcp

项目结构

hamcp-rs/
├── Cargo.toml          # Workspace root
├── flake.nix           # Nix flake (dev shell, package, NixOS module)
├── mcp/                # MCP server crate
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs     # Server entrypoint (streamable HTTP transport)
│       ├── lib.rs      # Library exports
│       ├── rest/       # Home Assistant REST API client
│       ├── websocket/  # Home Assistant WebSocket API client
│       └── models/     # Data models and MCP tool input types

许可证

看 许可证 了解详情。

相关 MCP