MCP Guard

A security scanner for Model Context Protocol servers.

A finding cannot exist without the observation that produced it: evidence is a required field with no default, and the report writer refuses to emit a report whose evidence does not point at something real. A static finding carries the literal source text at the position it names; a dynamic finding carries the exact bytes the server sent back, recorded by the transport before anything parses them. Command injection is proven by a canary that only a shell can produce, not inferred from a payload being accepted.

Contents

• Install
• Quickstart
• Sample output
• What it detects
• What it does not detect
• Architecture
• Scoring
• Usage
• Safety
• Accuracy
• Performance
• Development
• History
• License

Install

git clone https://github.com/SaravanaGuhan/mcp-guard.git
cd mcp-guard
pip install -e .

Python 3.11 or newer. Node is needed only to run dynamic analysis against Node.js targets.

Quickstart

# Static and dependency analysis. Executes nothing from the target.
mcp-guard path/to/mcp-server

# One screen: what ran, what did not, and the verdict.
mcp-guard path/to/mcp-server --format summary

Dynamic analysis launches the target and speaks JSON-RPC to it, so it runs the target’s code and is off by default:

# WARNING: this installs and RUNS the target's code on this machine.
mcp-guard path/to/mcp-server --allow-execute

# The same, isolated in a container.
mcp-guard path/to/mcp-server --allow-execute --sandbox docker

Sample output

From docs/generated/sample-output.txt, regenerated by make sample:

------------------------------------------------------------------------------
STAGES
------------------------------------------------------------------------------
  acquire       ran            0.02s
  detect        ran            0.00s
       server_type: nodejs
  static        ran            0.01s
       findings: 3
  dependencies  DID NOT RUN    0.00s
       reason: offline mode: OSV lookup skipped
  dynamic       ran            2.26s
       handshake_rtt_ms: 2.0
       launch_source: package.json main

------------------------------------------------------------------------------
FINDINGS
------------------------------------------------------------------------------
  total 5   critical 2  high 3  medium 0  low 0
  by source: static 3  dynamic 2  dependency 0