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 <可选: 当前配置.json的路径>

通过本地实例安装

1. 下载包：

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

2. 安装并构建依赖项：

cd heimdall && pnpm i && pnpm build

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

pnpm run setup <可选: 当前配置.json的路径> <可选: 本地 Heimdall 实例中 index.js 文件的路径，例如 /path/to/local/heimdall/dist/index.js>

配置

编辑服务器列表

要添加或更新可用服务器，只需更新位于 ~/.heimdall/config.json 的配置，就像您通常更新 mcpServers 配置 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 客户端在给定时间对代理可用的工具数量有限制。例如，Cursor 在所有服务器上仅支持最多 40 个工具，因此 controls.json 中 authorizedTools 的总和不能超过这个数字。

日志

对于正在运行的实例的日志，请前往 ~/.heimdall/logs。每个 MCP 客户端的 Heimdall 实例及其子服务器的日志存储在由随机 UUID 标识的不同目录中。

孤儿子进程

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

pkill -aif node

贡献

欢迎并鼓励贡献。如有任何问题、评论或关注，请联系 austin@shinzolabs.com。