Content
# 🛡️ 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)](https://nisake.github.io/shield-scanner/)**
---
## ✨ 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
```bash
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):
```json
{
"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: "Helloworld"
```
### 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)](https://nisake.github.io/shield-scanner/)** — 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
```bash
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](./LICENSE) © NISAKE
---
🛡️ Made by **NISAKE** · See also [README.ja.md](./README.ja.md) for the Japanese version.
