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

1. 安装并构建依赖项：

cd heimdall && pnpm i && pnpm build

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

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 客户端对代理在同一时间可用的工具有数量限制。例如，Cursor 最多支持来自所有服务器的 40 个工具，因此 controls.json 中的 authorizedTools 总数不能超过这个数字。

日志

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

孤立的子进程

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

pkill -aif node

贡献

我们欢迎并鼓励贡献。如有任何问题、意见或担忧，请联系austin@shinzolabs.com。