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.
What is Heimdall?
Heimdall is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to 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 a...
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.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Heimdall is a lightweight service to manage local MCP Server
Use Cases
Maintainer
Works with
Installation
NPM
npx -y heimdallManual Installation
npx -y heimdallConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Heimdall
Heimdall (published as @cardor/heimdall-mcp) is a transparent MCP proxy that wraps any local or remote MCP server to add observability, access control, and tracing. It intercepts all JSON-RPC messages, measures latency, stores traces in SQLite, PostgreSQL, or MySQL, enforces per-server allow/deny tool policies, and exports distributed spans to Jaeger via OTLP. Teams use it to audit exactly which MCP tools their AI agents are calling, block sensitive operations like file writes, and debug unexpected agent behavior by replaying traces.
Prerequisites
- Node.js 18 or later
- npm for installation
- A running MCP server to proxy (local subprocess or remote HTTP/SSE)
- Optional: PostgreSQL or MySQL for persistent trace storage (SQLite works out of the box)
- Optional: Jaeger for distributed tracing visualization
Install Heimdall globally
Install the @cardor/heimdall-mcp package globally so the heimdall-mcp CLI is available on your PATH.
npm install -g @cardor/heimdall-mcpInitialize a policy configuration file
Generate a heimdall.config.ts in your project (or a global config in ~/.config/heimdall/) that defines which tools to allow or deny per server.
heimdall-mcp init
# Or for a global config:
heimdall-mcp init --global --format jsonDefine tool access policies
Edit heimdall.config.ts to set allow/deny lists per server. Deny rules take precedence over allow rules. Blocked calls return a JSON-RPC error and are flagged in traces.
Update your MCP client config to route through Heimdall
Replace the direct MCP server command in your client config with heimdall-mcp, passing the original server command after --. Heimdall proxies all traffic while recording traces.
Validate the configuration and start using your client
Run the health command to validate your policy configuration before connecting clients.
heimdall-mcp healthHeimdall Examples
Client configuration
Wrap an existing MCP server (e.g., a filesystem server) with Heimdall in Claude Desktop. All calls are logged to SQLite and policy-checked before forwarding.
{
"mcpServers": {
"filesystem-guarded": {
"command": "heimdall-mcp",
"args": [
"--store", "sqlite://~/.mcp-traces/traces.db",
"--", "npx", "@modelcontextprotocol/server-filesystem", "/tmp"
]
}
}
}Prompts to try
Heimdall is transparent to the AI client — it uses the same prompts as the underlying server. Use these to verify that policies and tracing are working.
- "List the files in /tmp" (should succeed if list_directory is allowed)
- "Write a file to /tmp/test.txt" (should be blocked if write_file is denied)
- Check Jaeger at http://localhost:16686 to see traced MCP calls
- Review trace database: heimdall-mcp health to see recent call countsTroubleshooting Heimdall
Policy file is not being picked up
Heimdall looks for heimdall.config.ts or heimdall.config.json in the current working directory and in ~/.config/heimdall/. Run 'heimdall-mcp health' to see which config files were found and whether any parse errors exist.
SQLite database path with tilde (~) does not expand
Use the full absolute path instead of ~ in the --store argument: e.g., --store sqlite:///home/yourusername/.mcp-traces/traces.db. The tilde shorthand may not expand in all environments.
Downstream MCP server fails to start when wrapped by Heimdall
Test the underlying server command directly first (without Heimdall) to confirm it works. Add --debug to the Heimdall args to see stderr output from both Heimdall and the subprocess.
Frequently Asked Questions about Heimdall
What is Heimdall?
Heimdall is a Model Context Protocol (MCP) server that 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. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Heimdall?
Install via npm with the command: npx -y heimdall. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
Which AI clients work with Heimdall?
Heimdall works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Heimdall free to use?
Yes, Heimdall is open source and available under the Apache 2.0 license. You can use it freely in both personal and commercial projects.
Heimdall Alternatives — Similar Developer Tools Servers
Looking for alternatives to Heimdall? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Heimdall in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Heimdall?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.