@buildwithabid/mcp-shield

v1.0.0

Published

a month ago

Security scanner for MCP servers. Find vulnerabilities before your AI agent does.

                          _____ __    _      __    __
   ____ ___  _________   / ___// /_  (_)__  / /___/ /
  / __ `__ \/ ___/ __ \  \__ \/ __ \/ / _ \/ / __  /
 / / / / / / /__/ /_/ / ___/ / / / / /  __/ / /_/ /
/_/ /_/ /_/\___/ .___/ /____/_/ /_/_/\___/_/\__,_/
              /_/

mcp-shield

Security scanner for Model Context Protocol (MCP) servers

Find vulnerabilities, prompt injection, secrets leaks, and supply chain attacks in MCP servers — before your AI agent does.

Quick Start • Security Checks • MCP Server Mode • Documentation • Contributing

Why mcp-shield?

MCP servers are the new attack surface for AI applications. Recent research has found:

66% of MCP servers have at least one security vulnerability
Tool description injection is the #1 attack vector — malicious servers embed hidden instructions that manipulate the AI agent
Rug-pull attacks change tool behavior after a user approves them
Supply chain attacks through typosquatting and malicious npm packages are increasing

mcp-shield is a dedicated security scanner for the MCP ecosystem. It runs 7 security checks against any MCP server package, produces a scored report, and works as both a CLI tool and an MCP server itself.

Quick Start

Install and Run

Not published to a registry yet. Install from source with the steps below; the commands in this README assume you have done so.

git clone https://github.com/BuildWithAbid/mcp-shield.git
cd mcp-shield
npm install && npm run build
npm link            # makes `mcp-shield` available on your PATH

Scan an MCP Server

# Scan an npm package
mcp-shield scan @modelcontextprotocol/server-filesystem

# Scan a local project
mcp-shield scan ./my-mcp-server

# JSON output for CI/CD
mcp-shield scan @some/mcp-server --format json

# Markdown report saved to file
mcp-shield scan @some/mcp-server --format markdown --output report.md

# Quick scan (skip slow checks like rug-pull detection)
mcp-shield scan @some/mcp-server --quick

Example Output

🛡️  mcp-shield v1.0.0 — MCP Security Scanner

Scanning: @example/mcp-server-db v2.1.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 CRITICAL  Supply Chain: Package published 3 days ago
🔴 CRITICAL  Tool Injection: Hidden instruction pattern in tool "query"
🟠 HIGH      Permissions: Unconstrained shell commands in tool "execute"
🟠 HIGH      Secrets: Hardcoded API key in src/config.ts:14
🟡 MEDIUM    Dependencies: 2 moderate CVEs in transitive dependencies
🟢 LOW       Transport: CORS allows all origins
✅ PASS      Rug-Pull: Tool descriptions are static

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Score: 28/100 (FAIL)
3 critical · 2 high · 1 medium · 1 low · 1 pass

7 Security Checks

mcp-shield runs these scanners against every target:

1. Dependency Audit

Runs npm audit to find known CVEs in direct and transitive dependencies.

Severities: Critical, High, Medium, Low
Automatically generates a lock file if missing

2. Permission & Scope Check

Analyzes tool input schemas for overly broad permissions:

Unrestricted shell commands — tools that accept arbitrary commands without an enum or allowlist
Unrestricted file paths — tools without path pattern constraints (path traversal risk)
Raw SQL input — tools accepting raw SQL strings (SQL injection risk)
Unrestricted URLs — tools without URL validation (SSRF risk)
eval() / Function() — dynamic code execution
child_process — shell access

3. Tool Description Injection

Scans tool descriptions for prompt injection patterns:

Hidden instructions ("ignore previous instructions", "do not tell the user")
Role/persona override ("you are now", "act as")
Unicode tricks (zero-width characters, homoglyphs, RTL overrides)
Base64-encoded payloads
Markdown/HTML injection
Data exfiltration patterns

4. Rug-Pull Detection

Detects mutable tool descriptions that can change after approval:

Descriptions loaded from environment variables or config
Descriptions generated by function calls or network requests
Timer-based tool modification (setTimeout/setInterval)
Post-registration tool changes (setTools, updateTool)

5. Secrets Detection

Finds hardcoded secrets in source code and .env files:

AWS keys, OpenAI/Anthropic API keys, GitHub tokens
Stripe, Slack, Google, Twilio, SendGrid keys
Database connection strings, JWTs, private keys
Generic password/token/secret assignments
Smart placeholder detection (skips "your-key-here" etc.)

6. Transport Security

Checks transport-layer configuration:

HTTP instead of HTTPS for remote endpoints
Permissive CORS (Access-Control-Allow-Origin: *)
Credentials with wildcard CORS origin
Auth tokens in URL query strings
Disabled TLS verification (rejectUnauthorized: false)
Unprotected sensitive routes

7. Supply Chain Analysis

Checks npm metadata and package integrity:

Typosquatting detection via Levenshtein distance against known MCP packages
Recently published packages (< 30 days)
Single-maintainer risk
Packages mimicking official naming
Suspicious install scripts (preinstall, postinstall)
Scripts downloading remote code
Missing repository declaration

MCP Server Mode

mcp-shield also runs as an MCP server, so AI assistants can scan other MCP servers directly:

# Start the MCP server
mcp-shield serve

# Add to Claude Code
claude mcp add mcp-shield -- mcp-shield serve

Available MCP Tools

| Tool | Description | |------|-------------| | scan_package | Scan an npm MCP server package by name | | scan_local | Scan a local directory for security issues | | get_report | Get the last scan report (JSON, Markdown, or terminal format) |

Documentation

CLI Reference

Usage: mcp-shield scan [options] <target>

Arguments:
  target                  npm package name or local path to scan

Options:
  -f, --format <format>   Output format: terminal, json, markdown (default: "terminal")
  -o, --output <file>     Write report to file instead of stdout
  -q, --quick             Skip slow checks like rug-pull detection
  -h, --help              Display help

Usage: mcp-shield serve [options]

Start mcp-shield as an MCP server (stdio transport)

Options:
  -h, --help   Display help

Output Formats

| Format | Flag | Best For | |--------|------|----------| | Terminal | --format terminal (default) | Human-readable with colors and severity icons | | JSON | --format json | CI/CD pipelines, programmatic access | | Markdown | --format markdown | GitHub issues, pull requests, wikis |

Scoring System

Each finding deducts from a 100-point score:

| Severity | Penalty | Example | |----------|---------|---------| | Critical | -25 | eval() usage, hardcoded AWS key, typosquatting | | High | -15 | Unrestricted shell commands, prompt injection | | Medium | -5 | Permissive CORS, missing repo declaration | | Low | -2 | Single maintainer, CORS on local server | | Info | 0 | Informational notes | | Pass | 0 | Check passed cleanly |

Score >= 70 = PASS. Score < 70 = FAIL (exit code 1 for CI/CD integration).

Architecture

                  ┌─────────────┐
                  │   CLI / MCP  │  (index.ts / mcp-server.ts)
                  │   Server     │
                  └──────┬───────┘
                         │
                  ┌──────▼───────┐
                  │ Orchestrator │  (scanner/index.ts)
                  │  File Cache  │  Collects files once, shares across scanners
                  └──────┬───────┘
                         │
        ┌────────┬───────┼───────┬────────┬────────┬────────┐
        ▼        ▼       ▼       ▼        ▼        ▼        ▼
   ┌────────┐┌───────┐┌──────┐┌───────┐┌───────┐┌───────┐┌───────┐
   │Secrets ││ Deps  ││ Tool ││ Perms ││Rug-Pull││ Trans ││Supply │
   │  Leak  ││ Audit ││ Desc ││ Check ││Detect  ││  Sec  ││ Chain │
   └────────┘└───────┘└──────┘└───────┘└───────┘└───────┘└───────┘
        │        │       │       │        │        │        │
        └────────┴───────┴───────┴────────┴────────┴────────┘
                         │
                  ┌──────▼───────┐
                  │   Reporter   │  Terminal / JSON / Markdown
                  └──────────────┘

All 7 scanners run concurrently using Promise.allSettled, sharing a single file cache for maximum performance.

Use Cases

CI/CD Pipeline

# Fail the build if the MCP server has security issues
mcp-shield scan ./my-mcp-server --format json
# Exit code 1 if score < 70

Pre-Install Check

# Check an MCP server package before installing it
mcp-shield scan @unknown/mcp-server-database

Security Audit

# Generate a markdown report for a security review
mcp-shield scan @company/internal-mcp-server --format markdown --output audit-report.md

AI-Assisted Scanning

# Let Claude scan MCP servers from within a conversation
claude mcp add mcp-shield -- mcp-shield serve
# Then ask: "Scan @modelcontextprotocol/server-filesystem for security issues"

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup instructions and guidelines.

Areas Where Help Is Needed

New detection patterns — prompt injection techniques, secret formats, dangerous APIs
Live server scanning — connecting to running MCP servers to test tool responses
PyPI / pip support — extending to Python MCP servers
CI/CD integrations — GitHub Actions workflow, pre-commit hooks
Documentation — guides, tutorials, real-world examples

Related Projects

Model Context Protocol — the protocol specification
MCP TypeScript SDK — official TypeScript SDK
Claude Code — AI coding assistant with MCP support

License

MIT — free for personal and commercial use.