Heimdall

Heimdall

Heimdall は、ローカルの MCP Servers を管理する軽量サービスで、単一の npx コマンドでインストールできます。特定の MCP サーバーのツールを MCP クライアントに対して認可でき、デバイス上のすべての MCP クライアントから同じ設定にアクセスできます。

インストール

⚠️ 注意： 認証情報が予期せず失われるのを防ぐため、インストール前に MCP サーバーの設定をバックアップすることを強くおすすめします。

セットアップスクリプトでは、次の主な処理を行います。

• 指定したパスにある mcpServers 設定 JSON を ~/.heimdall/config.json に移動します
• 以前の mcpServers 設定パスの代わりに、heimdall の設定を 1 つ挿入します
• ~/.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 クライアントを実行している場合、Heimdall がすでにデバイスにセットアップされていることを前提として、新しいクライアントごとに次の config.json を設定すると、すべてのクライアントで同じ認可済みツールを利用できます。

{
  "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

貢献

貢献を歓迎し、奨励しています。ご質問、ご意見、ご懸念などがありましたら、[email protected] までご連絡ください。