README.md•4.34 kB
# 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.