mcp-guardian

MCP security scanner that detects prompt injection attacks in tool descriptions.

What It Detects

• Cross-tool instructions - Attempts to chain tool calls ("before using this tool", "first call", "you must execute")
• Privilege escalation - Attempts to override safety ("ignore previous instructions", "you are now", "bypass security")
• Data exfiltration - Attempts to send data externally (URLs, "send to", "upload to")
• Stealth directives - Hidden instructions in descriptions
• Sensitive path access - References to ~/.ssh, ~/.aws, credentials, etc.
• Encoded content - Base64, unicode escapes, hex encoding (potential obfuscation)

Installation

npm install mcp-guardian

Usage

CLI - Scan MCP Config

# Auto-detect Claude Desktop config
npx mcp-guardian

# Explicit config path
npx mcp-guardian /path/to/claude_desktop_config.json

# JSON output
npx mcp-guardian --json

CLI - Run as MCP Server

npx mcp-guardian --mcp

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-guardian": {
      "command": "npx",
      "args": ["-y", "mcp-guardian", "--mcp"]
    }
  }
}

Library Usage

import {
  scanToolDescription,
  scanToolDefinitions,
  isDescriptionSafe,
  verifyToolDefinitions,
} from "mcp-guardian";

// Scan a single tool description
const result = scanToolDescription("my_tool", "Tool description here");
if (result.status === "critical") {
  console.error("Potential injection:", result.issues);
}

// Quick safety check
if (!isDescriptionSafe("Before using this tool, first call...")) {
  console.warn("Suspicious description detected");
}

// Scan multiple tools
const tools = [
  { name: "tool1", description: "...", schema: {} },
  { name: "tool2", description: "...", schema: {} },
];
const serverResult = scanToolDefinitions(tools, "my-server");

// Tool pinning - detect changes
const pinResult = verifyToolDefinitions(tools);
if (pinResult.status === "changed") {
  console.warn("Tool definitions changed:", pinResult.changedTools);
}

Demo

Try mcp-guardian instantly with built-in poisoned tool examples:

npx mcp-guardian demo

This scans hardcoded examples demonstrating real attack patterns — no config file needed.

Expected output:

✅ filesystem (14 tools)
✅ memory (9 tools)
🔴 suspicious-tool (4 tools)
   └─ add: sensitive_path (~/.ssh)
   └─ format_text: privilege_escalation ("You are now")
   └─ search_docs: exfiltration (evil URL), sensitive_path (~/.aws/credentials)

Summary:
  📊 Total tools: 27
  ✅ Clean: 2
  ⚠️  Warning: 0
  🚨 Critical: 1

The poisoned server demonstrates real attack patterns from published security research. See examples/poisoned-server/README.md for details.

Detection Patterns

Critical Severity (38 patterns)

| Category | Examples | |----------|----------| | Cross-tool instruction | "before using this tool", "first call", "then execute", "always call" | | Privilege escalation | "ignore previous instructions", "override system", "you are now" | | Exfiltration | URLs, "send to", "post to", "forward to", "upload to" |

Warning Severity (13 patterns)

| Category | Examples | |----------|----------| | Sensitive paths | ~/.ssh, ~/.aws, /etc/passwd, .env, api_key | | Encoded content | Base64 strings, unicode escapes, hex encoding |

Pre-commit Integration

Using pre-commit framework

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/alexandriashai/mcp-guardian
    rev: v1.2.2
    hooks:
      - id: mcp-guardian

Using Husky

Add to .husky/pre-commit:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx mcp-guardian --sync --quiet

Using Lefthook

Add to lefthook.yml:

pre-commit:
  commands:
    mcp-guardian:
      glob: "claude_desktop_config.json"
      run: npx mcp-guardian --sync {staged_files}

Tool Pinning

MCP Guardian includes tool definition pinning - SHA-256 hashing of tool definitions to detect tampering:

import { verifyToolDefinitions, approveAllTools } from "mcp-guardian";

// Verify tools against stored baseline
const result = verifyToolDefinitions(tools);

// Status: "created" | "verified" | "changed" | "error"
if (result.status === "changed") {
  console.log("Modified tools:", result.changedTools);
  console.log("New tools:", result.newTools);
  console.log("Removed tools:", result.removedTools);
}

// Re-approve all tools (after review)
approveAllTools(tools);

Manifests are stored in ~/.mcp-guardian/tool-manifest.json.

Research References

This tool is informed by MCP security research from:

• Invariant Labs - MCP Security Research
• Microsoft - Prompt Injection Attacks
• Palo Alto Unit 42 - AI Security
• Simon Willison - Prompt Injection

License

MIT