MCP Heimdall

MCP Heimdall is an advanced environment architect and diagnostic tool for the Model Context Protocol. It helps you understand, verify, and fix your execution environment by offering actionable insights into system architecture, runtimes, dependencies, and environment variables.

How to use

You can run MCP Heimdall as a local MCP server within your workspace or connect to it remotely via an MCP client. Use the provided commands to integrate, configure, and start the server, then leverage the tool set to inspect runtimes, dependencies, connectivity, and environmental health. The Intelligent Advisor guides you toward the most effective corrective steps based on the checks Heimdall performs.

When you start Heimdall, you gain access to a consolidated set of checks that help you diagnose issues such as missing node_modules, outdated packages, Docker status, PATH anomalies, and environmental mismatches. Use the outputs to apply precise commands that restore alignment with your project requirements.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system. A modern shell (bash/zsh) is recommended for running commands.

Install and set up MCP Heimdall using the quick integration command. This configures Heimdall in your current workspace.

npx @lchampz/mcp-heimdall integrate

If you prefer to connect via an MCP registry entry, add Heimdall to your mcp.json or editor settings as shown.

{
  "servers": {
    "heimdall": {
      "command": "node",
      "args": ["path/to/mcp-heimdall/build/index.js"]
    }
  }
}

Developers can build and run Heimdall locally. Use npm to install dependencies, build the project, and start in development mode as needed.

npm install
npm run build
npm run dev

Additional notes

MCP Heimdall provides a comprehensive set of tools and checks to help you maintain a healthy execution environment for your MCP-based workflows. Use the integrated advisor to prioritize fixes and run the full suite of checks to surface issues early.

Available tools

system_info

Collects OS and architecture details to understand the runtime environment.

inspect_runtimes

Checks versions of Node, Python, Java, and Kotlin to ensure they meet project requirements.

inspect_docker

Verifies Docker daemon status and lists containers to assess containerized workloads.

check_connectivity

Tests connectivity to essential services like GitHub, NPM, and Docker Hub.

project_doctor

Scans the project for NPM vulnerabilities and outdated packages.

resource_watcher

Monitors CPU usage, memory consumption, and disk space in real time.

workspace_janitor

Finds large files and temporary directories for cleanup.

path_inspector

Audits the PATH variable and verifies critical dev tool versions.

process_explorer

Identifies top resource-consuming processes and orphaned processes.

audit_dependencies

Detects missing packages or broken environments like missing node_modules.

audit_env

Compares .env files against templates and flags missing keys.

list_ports

Lists active listening ports and maps them to their processes.

kill_port_process

Terminates the process occupying a specific port.

suggest_corrections

Runs all checks and returns prioritized commands to fix environment issues.