Heimdall

Heimdall

Heimdall is a lightweight service to manage local MCP Servers 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.

Category
Visit Server

README

Heimdall

npm version smithery badge

Heimdall is a lightweight service to manage local MCP Servers 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 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:
git clone https://github.com/shinzo-labs/heimdall.git
  1. Install and build dependencies:
cd heimdall && pnpm i && pnpm build
  1. 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:

{
  "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):

{
  "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:

pkill -aif node

Contributing

Contributions are welcomed and encouraged. Contact austin@shinzolabs.com with any questions, comments or concerns.

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

Official
Featured
Local
TypeScript
VeyraX MCP

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official
Featured
Local
graphlit-mcp-server

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official
Featured
TypeScript
Kagi MCP Server

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official
Featured
Python
E2B

E2B

Using MCP to run code via e2b.

Official
Featured
Neon Database

Neon Database

MCP server for interacting with Neon Management API and databases

Official
Featured
Exa Search

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official
Featured
Qdrant Server

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official
Featured