# heimdall [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/caglarbozkurt/mcp-heimdall  
**GitHub Stars:** 0  
**npm Downloads (last month):** 196  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/heimdall

## Description
Scan an MCP server or agent config for injection, exfiltration, and risky capabilities.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "heimdall": {
    "command": "npx",
    "args": ["-y","mcp-heimdall-scan"]
  }
}
```

## Documentation

## What the heimdall MCP server does

The heimdall MCP server examines MCP servers and agent configurations before they are trusted. It can accept an npm package, PyPI package, local directory, Git repository URL, `tools.json` dump, or MCP client configuration. The scanner also supports supplementing source analysis with a `tools/list` dump containing tools, resources, and prompts.

Its checks cover prompt and tool-description injection, including hidden characters, concealment, override language, and fake `<IMPORTANT>` tags. It inventories filesystem, network, shell, dynamic evaluation, and credential-related access such as SSH, AWS, keychain, and `.env` use. Data-flow analysis can identify located paths such as secret-to-network or fetch-to-eval rather than treating unrelated capabilities as proof of abuse.

The report also considers install-time scripts, repository and license metadata, dependency-inherited capabilities, optional OSV.dev advisories, cross-server exfiltration chains, tool-name collisions, and changes from a previous report. Findings cite a file and line or a tool name where available.

## How it works

Analysis runs locally and is offline by default. The normal scan downloads or reads the target but does not execute the server, allowing a package to be reviewed before installation. A policy converts detector facts into a verdict: the built-in default, `strict`, or a user-supplied JSON policy can deny capabilities, require provenance, set severity thresholds, and record time-limited waivers.

The command-line interface uses `heimdall <target> [options]`. It returns exit code 0 for pass or warn, 1 for fail, and 2 for an error. JSON output supports automation, while SARIF 2.1.0 output can be used with code-scanning workflows. A baseline can be supplied to detect changes in a server's tool surface. The `--online` option checks declared dependencies against OSV.dev and sends dependency names for that lookup.

A separate `validate` mode performs a behavioral cross-check by running a server with capability recording and driving its tools.

## Setup and configuration

For a one-off scan, use `npx mcp-heimdall-scan` with a package, path, URL, or configuration file. Node.js 18.17 or newer is indicated by the project metadata. The package also exports a TypeScript `scan` function for programmatic use.

To expose the scanner through MCP, configure an MCP client to launch `npx -y --package mcp-heimdall-scan heimdall-mcp`. The resulting `scan_mcp_server` tool accepts a target plus optional policy and online settings. This MCP interface is static-only: handshake and validation execution modes are not exposed to the agent.

For CI, the project provides a GitHub Action. Its inputs include the required target, a default or strict policy or policy-file path, optional OSV.dev checking, SARIF output, failure behavior, and a package version pin. The scan runs on the CI runner without a backend.

## Tools and capabilities

The heimdall MCP server exposes `scan_mcp_server`, which can inspect npm and PyPI targets, local paths, GitHub URLs, tools/list files, and client configuration files. CLI capabilities include:

- Injection and risky-capability detection
- Proven data-flow and cross-server composition analysis
- Provenance, dependency, and optional CVE checks
- Baseline drift detection
- Policy-based pass, warn, or fail decisions
- JSON and SARIF reports

Use it when a model needs to assess an MCP target before adding it to its active configuration, or when a build should reject a configuration that violates procurement or security rules.

_Full upstream README: https://allmcps.com/mcp/heimdall/readme_