Heimdall

Heimdall

Heimdall 是一款轻量级服务，用于管理本地 MCP 服务，只需运行一条 npx 命令即可安装。你可以为 MCP 客户端授权特定的 MCP 服务工具，并且设备上的所有 MCP 客户端都可以访问同一份配置。

安装

⚠️ 注意：我们强烈建议在安装前备份 MCP 服务配置，以防凭据意外丢失。

设置脚本会执行以下几项关键操作：

• 将你指定路径中的 mcpServers 配置 JSON 移至 ~/.heimdall/config.json
• 在原 mcpServers 配置路径中插入 Heimdall 的单条配置
• 在 ~/.heimdall/controls.json 中初始化控制项，为所有现有服务授权所有方法

请参阅配置，了解如何修改 ~/.heimdall/controls.json 来限制特定服务的授权工具，以及如何向 ~/.heimdall/config.json 添加新服务。

通过 NPX 安装（推荐）

1. 运行设置脚本（如果未提供路径，则会生成空配置）：

npx @shinzolabs/heimdall setup <optional: path/to/current/config.json>

通过本地实例安装

1. 下载软件包：

git clone https://github.com/shinzo-labs/heimdall.git

2. 安装并构建依赖项：

cd heimdall && pnpm i && pnpm build

3. 运行设置脚本（如果未提供路径，则会生成空配置）：

pnpm run setup <optional: path/to/current/config.json> <optional: path to `index.js` file in local Heimdall instance, ex. `/path/to/local/heimdall/dist/index.js`>

配置

编辑服务列表

要添加或更新可用服务，只需像常规 mcpServers 配置 JSON 一样更新 ~/.heimdall/config.json。请注意，如果不同时在 ~/.heimdall/controls.json 中添加服务及其授权工具，你将无法通过 Heimdall 看到新服务的工具。

编辑授权工具

要为新服务或现有服务添加授权工具，请按需将它们添加到 ~/.heimdall/controls.json，Heimdall 会在几秒后更新其内部配置。如果你的 MCP 客户端支持动态缓存工具列表，你应该会看到授权工具自动更新。其他客户端（例如 Claude Desktop）可能需要重启才能看到新工具。

以下是 ~/.heimdall/controls.json 的架构：

{
  "authorizedMcpServers": {
    "server1": {
      "authorizedTools": [
        "tool1",
        "tool2",
        ...
      ]
    },
    "server2": {
      "authorizedTools": [
        "tool1",
        "tool2",
        ...
      ]
    }

多个 MCP 客户端

如果设备上运行着多个 MCP 客户端，可以为每个新客户端设置以下 config.json，以便在所有客户端上启用相同的授权工具（假设 Heimdall 已在设备上完成设置）：

{
  "mcpServers": {
    "heimdall": {
      "command": "npx",
      "args": [
        "@shinzolabs/heimdall"
      ]
    }
  }
}

故障排除

可用工具

某些 MCP 客户端对 Agent 在特定时间可用的工具数量有限制。例如，Cursor 在所有服务中最多支持 40 个工具，因此 controls.json 中 authorizedTools 的总数不能超过此限制。

日志

要查看正在运行的实例的日志，请前往 ~/.heimdall/logs。每个 MCP 客户端的 Heimdall 实例及其子服务的日志都存储在以随机 UUID 标识的独立目录中。

孤立的子进程

如果 MCP 客户端意外关闭，或未在关闭前向 Heimdall 发送正确的 SIGTERM 信号，之后设备上可能仍会有孤立的 node（和 npm）进程。目前必须手动强制终止这些进程。如果设备上没有其他正在运行的敏感 node 进程，可以使用以下命令进行清理：

pkill -aif node

贡献

欢迎并鼓励大家贡献。如有任何问题、意见或顾虑，请联系 [email protected]。