mcpwatch

Security scanner for MCP (Model Context Protocol) servers and configurations.

MCP has become the standard way AI agents connect to tools, files, and credentials. But shipped MCP servers are routinely exposed to tool poisoning, prompt injection, and over-privileged scopes — and most projects have no security check in CI.

mcpwatch scans MCP manifests, tool descriptions, and server code for these risks, locally or in your CI pipeline.

Status

Early development. See ROADMAP.md for the release plan and CHANGELOG.md for what has shipped.

| Feature | Status | |---|---| | Static rule engine (41 rules, mapped to OWASP LLM Top 10) | shipped | | CLI: text / JSON / SARIF / HTML output | shipped | | GitHub Action with Code Scanning integration | shipped | | Self-contained HTML report (--format html) | shipped | | Optional LLM-assisted semantic analysis (bring your own key, MG900) | shipped | | Rug-pull detection: tool-description drift against a baseline (MG701–MG703) | shipped | | Auto-fix: safe rewrites for zero-width descriptions and http→https endpoints (MG004/MG012) | shipped | | Config file .mcpwatchrc / .mcpwatchrc.json: include/exclude paths, ignore rules, severity threshold, and a failOn CI gate | shipped |

Install

npm install -g @dutjr1/mcpwatch
# or run without installing
npx @dutjr1/mcpwatch scan .

Quick start

# scan the current directory, human-readable output
mcpwatch scan .

# machine-readable output
mcpwatch scan . --format json

# SARIF for GitHub Code Scanning
mcpwatch scan . --format sarif > results.sarif

# self-contained HTML report (single file, inline CSS, no network needed)
mcpwatch scan . --format html > report.html

# capture a trust baseline, then detect rug-pull description drift
mcpwatch baseline ./config
mcpwatch scan ./config --baseline ./config

# preview safe auto-fixes, then apply them (originals backed up to .bak)
mcpwatch scan ./config --fix
mcpwatch scan ./config --fix --yes

The exit code is 1 when any error-severity finding is present, so it works as a CI gate.

Configuration

mcpwatch can read a config file so you don't repeat flags on every run. Drop a .mcpwatchrc or .mcpwatchrc.json in your project root (or pass --config <path>), and it will control which files are scanned, which rules run, how loud the report is, and how strict the failure gate is:

# only scan src/, ignore MG012, and never fail the build on findings
mcpwatch scan . --config .mcpwatchrc.json

# one-off override of the failure gate
mcpwatch scan . --fail-on warning

Config options include include / exclude (path filtering), ignoreRules (with MG0* wildcards), a severityThreshold, failOn (error | warning | info | none), and format. A _mcpwatch-ignore key or a .mcpwatchignore file offers inline rule silencing. The CLI flag always wins over the file. Full schema, precedence rules, and GitHub Actions + GitLab CI recipes are in docs/config.md.

Use in GitHub Actions

mcpwatch ships as a composite Action. Drop it into any repo's workflow to scan MCP servers and configs on every push or PR:

- uses: DUTJR1/[email protected]
  with:
    path: "."
    fail-on-error: true

It writes mcpwatch-results.sarif. Pair it with github/codeql-action/upload-sarif to surface results in GitHub code scanning, or with marocchino/sticky-pull-request-comment to post the report on PRs. Full recipes in docs/action.md.

How it works

Every check is a small rule with an id like MG001. Rules examine MCP config files, tool descriptions, and server source code. Each rule ships with a real attack sample it was built from — the full catalog lives in docs/rules.md (MG000–MG040, drift rules MG701–MG703, and the LLM-assisted MG900).

Ecosystem scan

mcpwatch runs periodic scans of real open-source MCP servers to measure coverage, surface genuine hardening gaps, and catch its own false positives. The 16-repo scan (7 official modelcontextprotocol/servers subdirs + 9 third-party servers) is reproducible from this repository:

# clones/shallow-pulls the repo list, runs the production engine, writes the report
bash scripts/scan-ecosystem.sh

This produces docs/ecosystem-report.md (method, per-repo results table, by-rule and by-severity distributions, false-positive handling, and a comparison with the Invariant Labs MCP threat landscape and OWASP LLM Top 10) and the machine-readable reference/ecosystem-results.json. The repo list lives in scripts/ecosystem-repos.json and the per-repo verdicts (every finding manually verified) in scripts/ecosystem-verdicts.json. Latest run: 16 repos / 2089 files / 982 findings in 3389 ms total. No issues are filed against the scanned projects by this process — only draft reports are produced.

Contributing

See CONTRIBUTING.md. Bug reports and rule ideas are welcome in issues.

Security

To report a vulnerability in mcpwatch itself, see SECURITY.md.

License

Apache-2.0