Heimdall

Heimdall 是一个轻量级的服务，用于管理本地 MCP 服务器，可以通过单个 npx 命令安装。可以为您的 MCP 客户端授权特定的 MCP 服务器工具，并且相同的配置可以被您设备上的所有 MCP 客户端访问。

安装

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

安装脚本执行以下几个关键操作：

• 将您指定的路径中的 mcpServers 配置 JSON 移动到 ~/.heimdall/config.json
• 插入一个 heimdall 的配置来代替之前的 mcpServers 配置路径
• 初始化 ~/.heimdall/controls.json 中的控件，以授权所有当前服务器上的所有方法

请参阅 配置 了解修改 ~/.heimdall/controls.json 以限制给定服务器的授权工具，以及将新服务器添加到 ~/.heimdall/config.json 的步骤。

通过 NPX (推荐)

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

npx @shinzolabs/heimdall setup <可选: 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 <可选: path/to/current/config.json> <可选: 本地 Heimdall 实例中 `index.js` 文件的路径，例如 `/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。