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 | 获取历史状态数据 |
先决条件
- 正在运行的Home Assistant实例
- A. 长期访问令牌
快速开始
使用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://: /mcp 使用流式HTTP传输。
将MCP客户端指向端点：
http://your-server:3000/mcpMCP检验员测试
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-commitNix构建
薄片使用 起重机 带有锈层。起重机缓存 依赖关系是单独构建的，因此增量重建很快。
# 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许可证
看 许可证 了解详情。