heimdall

# Heimdall [](https://badge.fury.io/js/@shinzolabs%2Fheimdall) [](https://smithery.ai/server/@shinzo-labs/heimdall) Heimdall is a lightweight service to manage local [MCP Servers](https://modelcontextprotocol.io/introduction) and can be installed with a single `npx` command. Specific MCP server tools can be authorized for your MCP clients, and the same config is accessible to all MCP clients on your device. ## Installation ⚠️ <strong>NOTE:</strong> We strongly recommend backing up your MCP server config before installation to protect against unexpected loss of credentials. The setup script performs a few key actions: - Moves the `mcpServers` config JSON from the path you specify to `~/.heimdall/config.json` - Inserts a single config for `heimdall` in place of the previous `mcpServers` config path - Initializes the controls at `~/.heimdall/controls.json` to authorize all methods on all current servers See [Configuration](#configuration) for steps to modify `~/.heimdall/controls.json` to limit the authorized tools for a given server, and add new servers to `~/.heimdall/config.json`. ### Via NPX (Recommended) 1. Run setup script (generates an empty config if no path is given): ``` npx @shinzolabs/heimdall setup <optional: path/to/current/config.json> ``` ### Via Local Instance 1. Download the package: ```bash git clone https://github.com/shinzo-labs/heimdall.git ``` 2. Install and build dependencies: ```bash cd heimdall && pnpm i && pnpm build ``` 3. Run setup script (generates an empty config if no path is given): ``` 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`> ``` ## Configuration ### Edit Server List To add or update available servers, simply update the configuration at `~/.heimdall/config.json` as your regular `mcpServers` config JSON. Note that you will not see tools for new servers through Heimdall unless you also add the server and authorized tools to `~/.heimdall/controls.json`. ### Edit Authorized Tools To add authorized tools to a new or existing server, add them as needed to `~/.heimdall/controls.json` and Heimdall will update its internal config after a few seconds. If your MCP client supports dynamic tool list caching, you should see it update the authorized tools automatically. Other clients (ex. Claude Desktop) may require a restart to see the new tools. This is the schema for `~/.heimdall/controls.json`: ```javascript { "authorizedMcpServers": { "server1": { "authorizedTools": [ "tool1", "tool2", ... ] }, "server2": { "authorizedTools": [ "tool1", "tool2", ... ] } ``` ### Multiple MCP Clients If you run multiple MCP clients on your device, you can set the following `config.json` for each new client to enable the same authorized tools across all of them (assuming Heimdall has already been set up on the device): ```javascript { "mcpServers": { "heimdall": { "command": "npx", "args": [ "@shinzolabs/heimdall" ] } } } ``` ## Troubleshooting ### Available Tools Some MCP Clients have limits on the number of tools available to agents at a given time. For example, Cursor only supports up to 40 tools across all servers, so the sum of `authorizedTools` in `controls.json` cannot exceed this number. ### Logging For logs on running instances, go to `~/.heimdall/logs`. Logs for each MCP client's instance of Heimdall and child servers are stored in separate directories identified by random UUIDs. ### Orphaned Child Processes If your MCP client shut downs unexpectedly or fails to send the correct `SIGTERM` signal to Heimdall before closing, there may be orphaned `node` (and `npm`) processes still running on your device afterward. For the time being these must be force stopped manually. If there are no other sensitive `node` processes running on your device, you can use this command as post-cleanup: ```bash pkill -aif node ``` ## Contributing Contributions are welcomed and encouraged. Contact austin@shinzolabs.com with any questions, comments or concerns.