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

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.

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

Feature	Description	Install
neo4j	Neo4j knowledge graph for vulnerability similarity search	--features neo4j
redis	Redis distributed cache backend	--features redis

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>

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:
  -t, --timeout <seconds>    Timeout for server operations [default: 30]
  -f, --format <format>      Output format: text, json, sarif, junit, gitlab
  -c, --config <path>        Path to MCP config file

scan

Scan for security vulnerabilities.

mcplint scan <server> [options]

Options:
  -p, --profile <profile>    Scan profile: quick, standard, full, enterprise
  -i, --include <rules>      Include specific rule categories
  -e, --exclude <rules>      Exclude specific rule categories
  -t, --timeout <seconds>    Timeout [default: 60]
  --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
  -t, --timeout <seconds>    Timeout per server [default: 60]
  --fail-on <severities>     Fail only on specified severities
  -f, --format <format>      Output format (sarif for CI/CD)

# 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.

mcplint fuzz <server> [options]

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

explain

AI-powered explanations for security findings.

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
  -n, --max-findings <n>     Max findings to explain

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]
  -f, --format <format>      Output format: text, json

# 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]

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:

Category	Rules	Description
Protocol	PROTO-001 to PROTO-015	JSON-RPC 2.0 compliance, MCP version
Schema	SCHEMA-001 to SCHEMA-005	JSON Schema validation
Sequence	SEQ-001 to SEQ-003	Method call sequences
Tool	TOOL-001 to TOOL-005	Tool invocation
Resource	RES-001 to RES-003	Resource listing and reading
Security	SEC-001 to SEC-015	Path traversal, injection, SSRF, XXE, template injection, prompt injection, tool shadowing
Edge	EDGE-001 to EDGE-010	Null bytes, deep nesting, overflow, timeouts

Run mcplint rules --details to see all rules.

Security Rules (Scanner)

20+ rules for vulnerability detection:

Category	Description
injection	Command injection, SQL injection, path traversal, SSRF
auth	Authentication, credential exposure, OAuth scope abuse
transport	TLS/SSL security
protocol	Tool poisoning, shadowing, rug pull detection
data	Data exposure
dos	Denial of service

Output Formats

Format	Flag	Use
text	--format text	Terminal output (default)
json	--format json	Machine-parseable
sarif	--format sarif	GitHub Code Scanning
junit	--format junit	Test runners
gitlab	--format gitlab	GitLab Code Quality
html	--format html	Rich HTML reports with charts

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

Code	Meaning
0	Success, no findings
1	Success, findings detected
2	Error
3	Partial success
4	Timeout

License

MIT