Heimdall

What is Heimdall?

Heimdall is a lightweight service to manage local MCP Servers, installed with a single npx command. It moves your existing MCP server configuration to a centralized location and allows you to authorize specific tools for each server, making that configuration accessible to all MCP clients on your device.

How to use Heimdall?

Run the setup script via npx: npx @shinzolabs/heimdall setup <optional: path/to/current/config.json>. This moves your mcpServers config to ~/.heimdall/config.json and inserts a single Heimdall entry in its place. Then configure authorized tools in ~/.heimdall/controls.json and add the Heimdall configuration to each MCP client's config.

Key features of Heimdall

• Centralized MCP server configuration in ~/.heimdall/config.json
• Per-server authorization of tools via ~/.heimdall/controls.json
• Same configuration accessible to all MCP clients on your device
• Simple setup with a single npx command
• Logs stored at ~/.heimdall/logs for debugging

Use cases of Heimdall

• Manage multiple MCP servers across different clients without duplicating configuration
• Restrict which tools an MCP client can use on a per-server basis
• Quickly onboard new MCP clients by reusing the same Heimdall entry

FAQ from Heimdall

How does Heimdall modify my existing MCP config?

The setup script moves your mcpServers config JSON to ~/.heimdall/config.json and inserts a single heimdall configuration entry in its place at the original path.

What dependencies or runtime does Heimdall require?

Heimdall is a Node.js package installed via npx, so it requires Node.js and npm already available on your system.

Where are Heimdall’s config and logs stored?

Config is at ~/.heimdall/config.json, controls at ~/.heimdall/controls.json, and logs at ~/.heimdall/logs.

Are there known limits on the number of tools?

Some MCP clients, like Cursor, limit the total number of tools across all servers (e.g., 40). The sum of authorizedTools in controls.json must not exceed that limit.

How does Heimdall handle authentication or transport?

The README does not provide specifics on authentication or transport beyond using the standard MCP client-server command setup (npx). It relies on the existing MCP protocol transport.