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