https://github.com/shinzo-labs/heimdall
Control the tools your MCP-enabled agents can access with minimal overhead.
https://github.com/shinzo-labs/heimdall
Last synced: 2 months ago
JSON representation
Control the tools your MCP-enabled agents can access with minimal overhead.
- Host: GitHub
- URL: https://github.com/shinzo-labs/heimdall
- Owner: shinzo-labs
- License: mit
- Created: 2025-03-29T07:35:29.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-04-02T18:00:29.000Z (6 months ago)
- Last Synced: 2025-07-18T15:19:05.602Z (3 months ago)
- Language: JavaScript
- Homepage:
- Size: 54.7 KB
- Stars: 10
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - Heimdall - Tool to manage agent tools and MCP server configurations, helping orchestrate and configure multiple MCP servers. Directly relevant as an MCP server management tool. ([Read more](/details/heimdall.md)) `orchestration` `server-management` `mcp` `configuration` `agent-framework` (MCP Middleware & Orchestration)
- mcp-index - Heimdall - Manage local MCP Servers and authorize specific tools across MCP clients. Provides a lightweight service for configuring and maintaining MCP server settings. (Task and Project Management)
README
# 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
⚠️ NOTE: 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
```
### 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
```
## 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.