霍马尔·麦克普
MCP服务器 霍马尔 仪表板管理。通过模型上下文协议以编程方式管理板、应用程序、组和用户。
特性
- 板子：列出、创建、复制、重命名、删除、更改可见性、查看权限
- 应用：列出、获取、创建、更新、删除应用程序磁贴/书签
- 群组：列出、获取、添加/删除成员
- 用户：列表，搜索
设置
先决条件
- Python 3.12+
- 紫外线 包管理器
- 带有API密钥的正在运行的Homarr实例
安装
git clone https://github.com/TETRA-2023/homarr-mcp.git
cd homarr-mcp
uv sync配置
cp .env.example .env
# Edit .env with your Homarr URL and API key在Homarr中创建一个API密钥： 管理>工具>API密钥
| 变量 | 描述 | 默认值 |
|---|---|---|
HOMARR_URL | Homarr实例URL | http://localhost:7575 |
HOMARR_API_KEY | API密钥(. 格式） | *必需的* |
HOMARR_TRANSPORT | 运输方式(stdio, sse, streamable-http) | stdio |
MCP_HOST | HTTP传输的绑定地址 | 127.0.0.1 |
MCP_PORT | HTTP传输的侦听端口 | 8000 |
MCP_BEARER_TOKEN | 在HTTP传输上强制使用可选承载令牌（stdio没有操作） | *取消设置* |
用法
stdio（克劳德代码/本地）
uv run python src/server.py可流式传输的http（Docker/remote）
uv run python src/server.py --streamable-httpClaude代码配置
添加到您的Claude Code MCP设置中：
{
"mcpServers": {
"homarr": {
"command": "uv",
"args": ["run", "--directory", "/path/to/homarr-mcp", "python", "src/server.py"],
"env": {
"HOMARR_URL": "https://your-homarr-instance.com",
"HOMARR_API_KEY": "your_api_key_here"
}
}
}
}码头工人
docker build -t homarr-mcp .
docker run --env-file .env homarr-mcp --streamable-httpHTTP网关后的部署
当在包装器前面加上网关（LiteLLM、Kong、NGINX等）时 共享网络，设置 MCP_BEARER_TOKEN 一个随机的秘密。包装将 然后拒绝任何不匹配的HTTP请求 Authorization: Bearer 头球
export MCP_BEARER_TOKEN="$(openssl rand -hex 32)"
export HOMARR_TRANSPORT=streamable-http
export MCP_HOST=0.0.0.0 # bind to all interfaces inside the container
uv run python src/server.py客户端通过标准的承载方案传递令牌。使用a的示例 通用MCP客户端：
POST /mcp HTTP/1.1
Authorization: Bearer
Content-Type: application/json
Accept: application/json, text/event-stream
{"jsonrpc": "2.0", "method": "initialize", ...}笔记：
MCP_BEARER_TOKEN是 运输意识 --当
HOMARR_TRANSPORT=stdio （没有HTTP层）。现有stdio 消费者不受影响地工作。
- 这
Bearer方案名称不区分大小写匹配（RFC 7235§2.1）；
将令牌本身逐字节与 secrets.compare_digest 用于抵御定时神谕的恒定时间防御。
- 两条401路径（缺少标头、标记错误）都发出相同的主体，因此
客户无法区分它们。
- 在网关处将承载与TLS配对，这样令牌就不会在
电线。
- 要免除健康/探测路径的身份验证，请使用以下命令实例化中间件
skip_paths=("/healthz",).还没有公共的env-var钩子--添加一个 如果您在生产中需要，可以自定义入口点。
工具参考
板子
| 工具 | 说明 |
|---|---|
list_boards | 列出所有板 |
get_board | 按名称获取电路板（包括部分、项目、布局） |
create_board | 创建新板 |
duplicate_board | 按ID复制电路板 |
rename_board | 重命名板 |
delete_board | 删除板 |
change_board_visibility | 将板设置为公共或私人 |
get_board_permissions | 查看用户/组权限 |
应用
| 工具 | 说明 |
|---|---|
list_apps | 列出所有应用程序/书签 |
get_app | 按ID获取应用程序 |
create_app | 创建应用程序（名称、href、描述、icon_url、ping_url） |
update_app | 更新应用程序字段 |
delete_app | 删除应用程序 |
群组
| 工具 | 说明 |
|---|---|
list_groups | 列出所有有成员的组 |
get_group | 按ID获取组 |
add_group_member | 将用户添加到组 |
remove_group_member | 从组中删除用户 |
用户
| 工具 | 说明 |
|---|---|
list_users | 列出所有用户 |
search_users | 按姓名/电子邮件搜索用户 |
所有查询工具都支持 verbosity 参数： minimal, standard （默认），或 full.
发展
# Install dev dependencies
uv sync --all-extras --dev
# Run tests
uv run pytest tests/test_server.py -v
# Lint
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
# Pre-commit hooks
uv run pre-commit install许可证
麻省理工学院