Heimdall

🚀 Heimdall

Heimdall is a lightweight service designed to manage local MCP servers. It can be easily installed with a single npx command. You can authorize specific MCP server tools for MCP clients, and the same configuration will be available to all MCP clients on your device.

🚀 Quick Start

Heimdall simplifies the management of local MCP servers. With just a few steps, you can get it up and running.

✨ Features

• Lightweight service for managing local MCP servers.
• Easy installation via a single npx command.
• Authorize specific MCP server tools for MCP clients.
• Configuration is available to all MCP clients on the device.

📦 Installation

⚠️ Important Note

We strongly recommend backing up your MCP server configuration before installation to prevent accidental data loss.

The installation script performs the following key operations:

• Moves the mcpServers configuration JSON from the specified path to ~/.heimdall/config.json.
• Inserts a heimdall configuration at the previous mcpServers configuration path.
• Initializes the control file ~/.heimdall/controls.json to authorize all methods on all servers.

For information on how to modify ~/.heimdall/controls.json to restrict authorized tools for a given server and add new servers in ~/.heimdall/config.json, see Configuration.

Using NPX (Recommended)

1. Run the installation script (generates an empty configuration if no path is specified):

npx @shinzolabs/heimdall setup <Optional: path/to/current/config.json>

Using a Local Instance

1. Download the package:

git clone https://github.com/shinzo-labs/heimdall.git

2. Install and build the dependencies:

cd heimdall && pnpm i && pnpm build

3. Run the installation script (generates an empty configuration if no path is specified):

pnpm run setup <Optional: path/to/current/config.json> <Optional: Path to the `index.js` file in the local Heimdall instance, e.g., `/path/to/local/heimdall/dist/index.js`>

📚 Documentation

Configuration

Editing the Server List

To add or update available servers, directly modify the configuration file located at ~/.heimdall/config.json. The format is the same as the regular mcpServers configuration JSON. Note that you won't see the tools of a new server in Heimdall unless you also add the server and authorized tools to ~/.heimdall/controls.json.

Editing Authorized Tools

To add authorized tools for a new or existing server, add them to ~/.heimdall/controls.json. Heimdall will update its internal configuration within a few seconds. If your MCP client supports dynamic caching of the tool list, you should see the tools update automatically. If not, manually refresh as needed.

Example

Add the following to ~/.heimdall/controls.json to authorize specific tools:

{
  "authorized_tools": ["tool1", "tool2"]
}

Troubleshooting

Tools Not Displaying

• Ensure you have correctly added the server and tools to ~/.heimdall/controls.json.
• Check for spelling errors or formatting issues.
• Try manually refreshing the page or restarting the service.

Dependency Installation Failure

• Ensure you have a stable internet connection.
• Run the commands with administrator privileges.
• Check if package.json and package-lock.json exist.

🤝 Contribution

Contributions are welcome. If you have any questions, comments, or concerns, please contact austin@shinzolabs.com.