MCPLint

Security testing tool for Model Context Protocol (MCP) servers.

Features

• Protocol validation - verify MCP compliance with 56 validation rules
• Security scanning - detect vulnerabilities with 20+ detection rules
• Multi-server scanning - parallel scanning with aggregated results
• Coverage-guided fuzzing - find crashes and edge cases
• Tool fingerprinting - detect schema changes and breaking API updates
• AI-powered explanations - understand findings with remediation guidance
• Advanced prompt engineering - chain-of-thought reasoning with few-shot examples
• Neo4j knowledge graph - vector similarity search for related vulnerabilities (optional)
• Watch mode - differential display showing new/fixed issues
• Shell completions - bash, zsh, fish, PowerShell, elvish
• CI/CD integration - SARIF, JUnit, GitLab output formats
• Smart context detection - auto-detects TTY, CI, NO_COLOR modes
• Config file support - reads Claude Desktop config to find servers
• Interactive mode - guided wizards for scan, fuzz, and init commands

Installation

# From crates.io
cargo install mcplint

# From source
cargo install --path .

# With optional Neo4j knowledge graph support
cargo install mcplint --features neo4j

# Or build manually
cargo build --release
./target/release/mcplint --help

Optional Features

Quick Start

# List servers from Claude Desktop config
mcplint servers

# Validate a server
mcplint validate <server>

# Security scan
mcplint scan <server>

# Scan all servers in parallel
mcplint multi-scan --all

# Watch mode with differential display
mcplint watch <server>

Example Output

Scan the deliberately vulnerable demo server included in this repo to reproduce
this output. --quiet suppresses the startup banner and log lines; without it
the findings are identical but preceded by both.

$ mcplint scan examples/vulnerable-server/server.py --quiet

Starting security scan...
  Server: examples/vulnerable-server/server.py
  Command: python examples/vulnerable-server/server.py
  Profile: standard

Security Scan Results
------------------------------------------------------------

  Server: examples/vulnerable-server/server.py
  Profile: standard
  Checks: 5
  Duration: 5091ms

  2 vulnerabilities found:

  [CRITICAL] Tool Description Injection Detected (MCP-SEC-040)
    Tool 'summarize_notes' description contains prompt injection pattern that could manipulate AI behavior
    Location: tool: summarize_notes
    Fix: Remove all instruction-like content from tool descriptions. Tool descriptions should only explain the tool's functionality in neutral, factual terms without any directives to the AI.
    References: CWE-94, MCP-Security-Advisory-2025-02

  [HIGH] Cross-Server Tool Shadowing Detected (MCP-SEC-041)
    Tool 'run_command' exactly matches known tool 'run_command' from the shell MCP server. This could intercept calls intended for the legitimate tool, enabling data theft or manipulation.
    Location: tool: run_command
    Fix: Rename the tool to use a unique, server-specific prefix. For example, instead of 'read_file', use 'myserver_read_file' or 'custom_read_file'. This prevents tool shadowing and makes the tool's origin clear.
    References: CWE-706, MCP-Security-Advisory-2025-03

------------------------------------------------------------
Summary: 1 critical, 1 high, 0 medium, 0 low, 0 info
[ERROR] Server has critical/high severity vulnerabilities!

Exits 1 — findings detected. Duration varies per run; everything else is
deterministic for this server.

Interactive Mode

MCPLint includes interactive wizards that guide you through common operations when running in a terminal. Interactive mode automatically activates when:

• Running in a TTY (terminal)
• Not in a CI environment
• Command arguments are omitted

Scan Wizard

Run mcplint scan without arguments to launch the scan wizard:

mcplint scan
# Prompts for:
# - Server selection (from configured servers)
# - Scan profile (quick/standard/full/enterprise)
# - Categories to include
# - Output format
# - Severity threshold for failure

Fuzz Wizard

Run mcplint fuzz without arguments:

mcplint fuzz
# Prompts for:
# - Server selection
# - Fuzz profile (quick/standard/intensive/CI)
# - Duration
# - Number of workers
# - Corpus directory

Init Wizard

Run mcplint init to generate configuration with guidance:

mcplint init
# Prompts for:
# - Output path
# - Servers to test
# - Default scan profile
# - Create GitHub Actions workflow
# - Run initial scan

Explain Wizard

Run mcplint explain without arguments to get AI-powered explanations:

mcplint explain
# Prompts for:
# - Server selection
# - AI provider (Ollama/Anthropic/OpenAI)
# - Audience level (beginner/intermediate/expert)
# - Severity filter (optional)
# - Max findings to explain
# - Enable interactive follow-up Q&A

Interactive mode is disabled in CI environments or when piping output. Use explicit arguments for non-interactive execution.

Commands

# Core commands
mcplint validate <server>            # Validate protocol compliance
mcplint scan <server>                # Security scan
mcplint multi-scan --all             # Parallel multi-server scan
mcplint fuzz <server>                # Coverage-guided fuzzing
mcplint explain <server>             # AI-powered explanations
mcplint watch <server>               # Watch mode with live diffs

# Utility commands
mcplint servers                      # List configured servers
mcplint rules --details              # List all security rules
mcplint doctor                       # Environment check
mcplint fingerprint generate <s>     # Generate tool fingerprints
mcplint cache stats                  # Cache statistics
mcplint completions <shell>          # Generate shell completions
mcplint how-do-i <query>             # Contextual help
mcplint init                         # Generate config file

Command Reference

validate

Check MCP server for protocol compliance. Runs 56 validation rules across protocol, schema, sequence, tool, resource, security, and edge case categories.

mcplint validate <server> [options]

Options:
  -F, --features <features>  Check specific protocol features only
  -t, --timeout <seconds>    Timeout for server operations [default: 30]
  -c, --config <path>        Path to MCP config file

scan

Scan for security vulnerabilities. Server is optional in interactive mode (launches a wizard).

mcplint scan [<server>] [options]

Options:
  -p, --profile <profile>    Scan profile: quick, standard, full, enterprise [default: standard]
  -i, --include <rules>      Include specific rule categories
  -e, --exclude <rules>      Exclude specific rule categories
  -t, --timeout <seconds>    Timeout [default: 60]
  -c, --config <path>        Path to MCP config file
  --baseline <path>          Compare against baseline file
  --save-baseline <path>     Save results as baseline
  --update-baseline          Update existing baseline
  --diff-only                Show only diff summary
  --fail-on <severities>     Fail only on specified severities
  --explain                  Generate AI-powered explanations
  --ai-provider <provider>   AI provider for explanations

multi-scan

Scan multiple MCP servers in parallel.

mcplint multi-scan [options]

Options:
  -s, --servers <list>       Server names (comma-separated)
  --all                      Scan all configured servers
  -j, --concurrency <n>      Maximum concurrent scans [default: 4]
  -p, --profile <profile>    Scan profile for all servers [default: standard]
  -t, --timeout <seconds>    Timeout per server [default: 60]
  -c, --config <path>        Path to MCP config file
  --fail-on <severities>     Fail only on specified severities

# Examples
mcplint multi-scan --all --profile standard
mcplint multi-scan -s server1,server2 --format sarif
mcplint multi-scan --all --fail-on critical,high

fuzz

Coverage-guided fuzzing. Server is optional in interactive mode (launches a wizard).

mcplint fuzz [<server>] [options]

Options:
  -p, --profile <profile>    Fuzz profile: quick, standard, intensive, ci [default: standard]
  -d, --duration <seconds>   Duration to run [default: 300]
  -W, --workers <count>      Parallel workers [default: 4]
  -c, --corpus <path>        Corpus directory
  --max-memory <size>        Memory limit (e.g., 512MB)
  --max-time <time>          Time limit (e.g., 5m)

explain

AI-powered explanations for security findings. Server is optional in interactive mode (launches a wizard).

mcplint explain [<server>] [options]

Options:
  -P, --provider <provider>  AI provider: ollama, anthropic, openai [default: ollama]
  -m, --model <model>        Model to use
  -a, --audience <level>     Audience: beginner, intermediate, expert [default: intermediate]
  -s, --severity <severity>  Minimum severity to explain
  -n, --max-findings <n>     Max findings to explain
  -i, --interactive          Interactive follow-up Q&A
  -t, --timeout <seconds>    Timeout [default: 120]
  --no-cache                 Disable response caching

AI providers require environment variables:

• Anthropic: ANTHROPIC_API_KEY
• OpenAI: OPENAI_API_KEY
• Ollama: runs locally, no key needed

fingerprint

Generate and compare tool definition fingerprints to detect schema changes.

# Generate fingerprints
mcplint fingerprint generate <server> [options]

Options:
  -o, --output <path>        Save fingerprints to file
  -t, --timeout <seconds>    Timeout [default: 30]
  -c, --config <path>        Path to MCP config file

# Compare against baseline
mcplint fingerprint compare <server> --baseline <path> [options]

Options:
  -b, --baseline <path>      Baseline file for comparison (required)
  -t, --timeout <seconds>    Timeout [default: 30]
  -c, --config <path>        Path to MCP config file

Exit codes for compare:

• 0: No changes or minor/patch changes
• 1: Breaking changes detected
• 2: Major changes detected

See docs/fingerprinting.md for detailed documentation.

servers

List MCP servers from Claude Desktop config.

mcplint servers

watch

Watch files and rescan on changes with differential display.

mcplint watch <server> [options]

Options:
  -w, --watch <path>         Paths to watch [default: .]
  -p, --profile <profile>    Scan profile [default: quick]
  -d, --debounce <ms>        Debounce delay [default: 500]
  -c, --clear                Clear screen before each scan

# Shows differential output:
# ❌ NEW ISSUES - newly detected vulnerabilities
# ✅ FIXED - previously detected issues now resolved

completions

Generate shell completions with server name support.

mcplint completions <shell>

Shells: bash, zsh, fish, powershell, elvish

# Installation examples
mcplint completions bash >> ~/.bashrc
mcplint completions zsh >> ~/.zshrc
mcplint completions fish > ~/.config/fish/completions/mcplint.fish
mcplint completions powershell >> $PROFILE

cache

Manage cache storage.

mcplint cache stats          # show statistics
mcplint cache clear          # clear all entries
mcplint cache prune          # remove expired entries
mcplint cache keys           # list cache keys
mcplint cache export -o f    # export to file
mcplint cache import -i f    # import from file

Validation Rules

56 rules across 7 categories:

Run mcplint rules --details to see all rules.

Security Rules (Scanner)

20+ rules for vulnerability detection:

Output Formats

HTML Reports

Generate visual HTML reports with severity charts and detailed findings:

mcplint scan <server> --format html > report.html

HTML reports include:

• Severity distribution pie chart
• Finding cards with details
• Remediation guidance
• Responsive design for viewing on any device

Configuration

Create .mcplint.toml:

mcplint init

Example:

[scan]
profile = "standard"
exclude = ["MCP-DOS-002"]
fail_on = ["critical", "high"]

[fuzz]
duration = 600
workers = 8

[ai]
provider = "ollama"
model = "llama3.2"

Exit Codes

License

MIT