🛡️ mcp-guard

🛡️ mcp-guard

Security scanner for MCP server tool manifests. Audit any MCP server's tools/list response for dangerous capabilities before you connect it to your AI agent.

In 2026, 30+ MCP-related CVEs were filed including a 9.6 CVSS RCE. Only 12.9% of public MCP servers score "high trust." Tool poisoning — malicious tool descriptions injecting hidden directives — is now a recognized structural vulnerability. mcp-guard gives you an npm audit-like experience for the MCP ecosystem.

Complements ai-supply-guard (npm dependency audit) and agentguard (shell command safety gate).

Why mcp-guard?

• MCP servers have privileges — they can read/write files, execute commands, access the network. Before you connect one to your AI agent, know what it can do.
• One command, instant audit — mcp-guard scan gives you a risk score, per-tool verdicts, and actionable details. No config needed.
• CI-native — fail builds on dangerous tools. 10 configurable security rules with scoring and policy presets.
• Zero dependencies — pure Node.js stdlib. Nothing to install, nothing to trust.

Features

• 🔍 10 security rules covering shell exec, filesystem, network, secrets, database, auth, command injection, sensitive paths
• 📊 Risk scoring — per-tool risk score (0–100) with safe/caution/dangerous verdicts
• ⚙️ Configurable policies — presets (default/strict/permissive), rule disabling, tool allowlisting, custom thresholds
• 🎨 CLI + programmatic API — human-readable table or JSON output
• ✅ CI-ready — exits non-zero on dangerous tools
• 🚫 Zero runtime dependencies — pure Node.js stdlib

Quick Start

npm install -g mcp-guard

Usage

CLI

# Scan a tools/list manifest
mcp-guard scan manifest.json

# Pipe from an MCP probe
mcp-probe tools my-server | jq '{tools: .}' | mcp-guard scan --stdin

# JSON output for CI
mcp-guard scan manifest.json --json

# Strict mode (lower thresholds)
mcp-guard scan manifest.json --preset strict

# Allowlist trusted tools
mcp-guard scan manifest.json --allowlist safe_tool --allowlist makeCoffee

# Disable a specific rule
mcp-guard scan manifest.json --disable sensitive-paths

# List rules and presets
mcp-guard rules
mcp-guard presets

Output:

mcp-guard — DANGEROUS  5 tools, 2 safe, 1 caution, 2 dangerous  risk: 52/100

  ✓ hello                       0
  ✓ get_time                    0
  ⚠ read_file                  10 ██
  ✗ write_file                 20 ████
  ✗ execute_command            35 ███████

Details:

  read_file (risk: 10)
    [MED ] fs_read            Tool reads arbitrary files — potential data exfiltration risk

  write_file (risk: 20)
    [HIGH] fs_write           Tool writes files to arbitrary locations

  execute_command (risk: 35)
    [CRIT] shell_exec         Tool executes arbitrary system commands

Programmatic API

import { scanTool, scanManifest, loadPreset } from "mcp-guard";

// Scan a single tool
const result = scanTool({
  name: "execute_command",
  description: "Execute arbitrary shell commands",
});
console.log(result.verdict); // "dangerous"
console.log(result.riskScore); // 35

// Scan a full manifest
const report = scanManifest(
  { tools: [...] },
  loadPreset("strict"),
);
console.log(report.overallVerdict);
console.log(report.summary);

Manifest Format

mcp-guard expects the standard MCP tools/list response:

{
  "tools": [
    {
      "name": "read_file",
      "description": "Read a file from the filesystem",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the file"
          }
        }
      }
    }
  ]
}

Security Rules

Policy Presets

Development

git clone https://github.com/alvabillwu/mcp-guard.git
cd mcp-guard
npm install
npm test
npm run build

🔗 Ecosystem

Part of the alvabillwu AI/LLM DevTools suite:

• mcp-probe — CLI probe to inspect any MCP server
• mcp-compliance-lite — MCP spec conformance tester
• mcpindex — Searchable index and discovery tool for MCP servers
• mcp-factory — MCP server scaffolding CLI
• ai-supply-guard — NPM dependency security audit for AI projects

License

MIT © alvabillwu

⭐ Like this? Star the repo to support MCP security tooling!