🛡️ Shield Scanner MCP

Prompt Injection Detector for AI assistants — Model Context Protocol edition

Scan text, files, URLs, and emails for hidden prompt injection threats before they reach your LLM. Runs as an MCP server so Claude Desktop (or any MCP-compatible host) can call it directly during a conversation.

📎 Looking for a no-install browser version? Try the companion app: Shield Scanner (Web)

✨ Features

• 🔍 5 detection categories — Invisible Unicode, Control Characters, Hidden HTML, Suspicious Patterns, Homoglyphs
• 📁 Multi-format support — txt / md / csv / json / html / xml / svg / docx / pdf / pptx / eml
• 🌐 Pre-scan URLs — fetches raw HTML and inspects it before your AI reads the page
• 📧 Pre-scan emails — analyzes headers / body / HTML parts / attachment names separately
• 🧹 Sanitize — output a cleaned version with detected threats removed or normalized
• 🔒 Local-first — only network access is the URL-fetch tool; all detection runs locally with no telemetry

🛠️ Tools

| Tool | Description | |------|-------------| | scan_text | Scan raw text directly | | scan_file | Scan a file by path | | scan_url | Fetch a URL and scan the raw HTML | | scan_email | Scan an .eml file or raw email source | | sanitize_text | Return text with detected threats removed | | sanitize_file | Write a sanitized copy of a file |

All tools accept an optional categories array to limit which checks run.

📦 Installation

Requirements

• Node.js 18+
• An MCP-compatible host (e.g., Claude Desktop)

Step 1 — Clone & install

git clone https://github.com/nisake/shield-scanner-mcp.git
cd shield-scanner-mcp
npm install

Step 2 — Register with Claude Desktop

Open your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add an entry under mcpServers (use the absolute path to server/index.js on your machine):

{
  "mcpServers": {
    "shield-scanner": {
      "command": "node",
      "args": ["/absolute/path/to/shield-scanner-mcp/server/index.js"]
    }
  }
}

Restart Claude Desktop. You should see the Shield Scanner tools available in the tool list.

💡 Usage examples

Just ask Claude (or your MCP host) in natural language — it will pick the right tool.

> Scan this article before you read it: https://example.com/blog/post

> Check this email for prompt injection: C:\Users\me\Downloads\message.eml

> Is there any hidden text in this PDF? /Users/me/Documents/report.pdf

> Clean up this text and remove any invisible characters: "Hello​world"

Sample output

=== Shield Scanner Report ===
File: report.pdf
Date: 2026-05-25T10:30:00.000Z
Status: DANGER
Total findings: 4 (danger: 2, warning: 2)

[Invisible Unicode] 2 found
  - ZERO WIDTH SPACE U+200B at pos 142
  - LEFT-TO-RIGHT OVERRIDE U+202E at pos 287

[Control Characters] 0 found

[Hidden HTML] 1 found
  - white-text in <span>

[Suspicious Patterns] 1 found
  - prompt-injection-instruction: ignore all previous instructions

[Homoglyphs] 0 found

🔬 Detection categories

| Category | What it catches | |----------|-----------------| | Invisible Unicode | Zero-width spaces, RLO/LRO overrides, bidi controls, tag characters, and other non-printing codepoints commonly used to hide instructions | | Control Characters | C0/C1 control chars (excluding standard whitespace) that should not appear in normal documents | | Hidden HTML | White-on-white text, display:none, visibility:hidden, font-size:0, off-screen positioning, hidden form fields | | Suspicious Patterns | Known prompt-injection phrases ("ignore previous instructions", role hijacks, system prompt overrides, etc.) | | Homoglyphs | Look-alike characters from other scripts (Cyrillic а vs Latin a) used to bypass keyword filters |

🗺️ Roadmap

• v1.0 ✅ All 6 tools, multi-format file support, .eml parsing
• v1.1 — Gmail API integration (scan by message_id / thread_id directly)
• v1.2 — Custom rule packs (project-specific detection patterns)
• v1.3 — mcpb packaging for one-click install

🤝 Related project

This MCP server is the headless counterpart of Shield Scanner (Web) — a browser-based version that runs entirely client-side. Use the web version for ad-hoc one-off scans; use this MCP for automated pre-checks inside your AI workflow.

🧪 Testing

npm test

Runs the test suite in test/ to verify detector behavior against known injection samples.

🤲 Contributing

Issues and pull requests welcome. If you've spotted a new injection technique in the wild, please open an issue with a minimal reproduction — new rules go into server/rules/.

📜 License

MIT © NISAKE

🛡️ Made by NISAKE · See also README.ja.md for the Japanese version.