mcpxray

Static linter + 0–100 scorecard for MCP servers. mcpxray scans an MCP server's source (or a captured tools/list manifest) and flags tool poisoning, leaked secrets, dangerous capabilities, weak schemas and more — locally, deterministically, in CI. Point it at a GitHub URL or a local path and get a plain-language verdict — 🟢 ok / 🟡 caution / 🔴 danger — plus a 0–100 score and an SVG badge.

MCP is the fastest-growing dev protocol since GraphQL (~97M SDK downloads/month), yet 7%+ of servers ship with vulnerabilities and the OWASP MCP Top 10 is a list, not a tool. mcpxray is the missing npm audit + OpenSSF Scorecard for MCP — static, local-first, OSS.

Status

✅ v1.0.0 — stable public API. Python + TypeScript static extractors, manifest extractor, opt-in runtime tools/list capture, rules MCP101–109 (full OWASP MCP Top-10 mapping), check/scan/score/badge/version, plain/json/github/sarif/card reports, 0–100 score with error cap, SVG badge, --fix/--diff for MCP108, pre-commit hook, frozen plugin API (__all__ + SemVer policy), tokenless PyPI trusted publishing. 224 tests.

Install

uv tool install mcpxray-cli
# or: pip install mcpxray-cli

The PyPI distribution is mcpxray-cli (the name mcpxray is blocked on PyPI by an unrelated project); the command it installs is still mcpxray.

Requires Python ≥ 3.10.

Quick start

# Is this MCP server safe to install? Point mcpxray at a GitHub URL or a local path.
mcpxray check https://github.com/owner/repo
mcpxray check path/to/my-mcp-server

# Verdict + the full finding list
mcpxray check path/to/my-mcp-server --details

# Not a Python server? Hand mcpxray a captured tools/list dump (any language)
mcpxray check --manifest tools-list.json

# ...or spawn the server and let mcpxray capture tools/list live (any language)
mcpxray check --runtime --command "python -m my_mcp_server"

# --- power users / CI -----------------------------------------------------
# Lint and print findings (CI gate: --check exits 1 on any ERROR)
mcpxray scan path/to/my-mcp-server --check -f github
# Just the 0–100 score, fail below a bar
mcpxray score path/to/my-mcp-server --fail-under 80
# Embed an SVG score badge in your README
mcpxray badge path/to/my-mcp-server -o docs/score.svg

Commands

What the verdict means

mcpxray check turns findings into a traffic-light verdict instead of a raw score:

The numeric score (0–100, shown as a secondary detail) still follows the error-cap rule below: any error caps it at 60. --fail-under N adds a CI gate that is independent of the verdict (it can turn a 🟡/🟢 into an exit-1 without changing the displayed verdict).

Languages: mcpxray checks Python and TypeScript statically (FastMCP @mcp.tool and the TS SDK's server.tool(...) / registerTool(...) / low-level ListToolsRequestSchema shapes). Servers in other languages — or tools built dynamically at runtime — still return ⚪ UNKNOWN; capture tools/list (mcpxray check --manifest dump.json), or spawn the server and let mcpxray capture it live (mcpxray check --runtime --command '<launch>').

Runtime capture (--runtime --command)

When source isn't parseable (compiled, 3rd-party, or tools built dynamically), --runtime spawns the server, performs the MCP JSON-RPC handshake over stdio (initialize → notifications/initialized → tools/list), and feeds the captured tools through the same rules. It's strictly opt-in and needs an explicit launch command:

mcpxray check --runtime --command "python -m my_mcp_server"
mcpxray check --runtime --command "node dist/index.js" path/to/server   # cwd = the path

⚠️ --runtime executes the server under inspection. It is opt-in, runs the server with a bounded lifetime (timeouts + guaranteed teardown), and parses its response defensively — but provides no OS-level sandbox (no filesystem/network isolation). Only point it at servers you trust; for untrusted servers, run mcpxray inside a container or VM. Prefer --manifest when you already have a captured tools/list.

Runtime-captured tools carry no source text, so the source-scanning rules (MCP102 secrets / MCP103 RCE / MCP105 drift / MCP109 transport) can't fire — but schema and description rules (MCP104/106/107) still run on the captured definitions.

Auto-fix (scan --fix / --diff)

The one rule that's mechanically, unambiguously fixable is MCP108 (unpinned dependencies): scan --fix pins a floating spec to its concrete floor version — requests>=2.30.0 → requests==2.30.0 (pip), "zod": "^1.2.3" → "zod": "1.2.3" (npm). It edits pyproject.toml / package.json in place (atomically); --diff prints the same changes as a unified diff and writes nothing.

mcpxray scan path/to/server --diff     # preview (exits 1 if changes are pending — CI-friendly)
mcpxray scan path/to/server --fix      # apply in place

What it does not touch:

• No floor to pin (*, latest, a bare flask, >=2 with no patch) → skipped, left for you to resolve against a registry. mcpxray never invents a version.
• Specs with extras/env markers (pkg[extra]>=1.2.3, pkg>=1.2.3 ; python_version>'3') → skipped (rewriting them textually is unsafe).
• Every other rule (MCP101–107, MCP109) → not auto-fixable; these need human judgment (a leaked secret isn't "fixed" by deleting it).

--fix/--diff are static-source-only — they rewrite files in place, so they reject --manifest, --runtime, and URL targets (point them at a local path). Every edit is a literal, uniquely-anchored replacement, so an ambiguous match is skipped rather than applied wrongly. Re-run scan after --fix to confirm the score improved.

Rules

Each finding is a Diagnostic with a severity (error/warning/info). Any error caps the score at 60, so a leaked secret or poisoned tool can never be diluted into a green grade.

Score & grades

Deductions: error = −20, warning = −6, info = −1, clamped to [0, 100].

CI

# .github/workflows/mcp.yml
name: mcpxray
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv tool install mcpxray-cli
      # GitHub annotations + SARIF-friendly; fails on any ERROR
      - run: mcpxray scan ./src --check -f github
      # Optional: fail below a score bar
      - run: mcpxray score ./src --fail-under 80

Pre-commit hook

Lint on every commit from any MCP-server repo. Add mcpxray to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/cloudroad-io/mcpxray
    rev: v1.0.0          # pin to a release tag
    hooks:
      - id: mcpxray
        args: ["./src"]  # path to your server source

The hook runs mcpxray scan --check <path> and fails the commit on any ERROR (tool poisoning, leaked secrets, RCE). Requires the mcpxray-cli distribution on PyPI; if you install it locally instead (uv tool install mcpxray-cli), set language: system on the hook.

How it works

1. Extract. PythonExtractor walks .py files, finds @mcp.tool / @server.tool decorators, and lifts name, the docstring (→ description) and type hints (→ JSON Schema) straight from the AST — no imports, no execution. ManifestExtractor parses a captured tools/list JSON dump for servers in any language. For servers you can run, --runtime --command spawns it and captures tools/list live (runtime.py).
2. Lint. Each rule sees the resulting McpServer IR and emits Diagnostics.
3. Score. Findings collapse to a 0–100 score with an error cap (mirrors OpenSSF Scorecard's shape).
4. Report. plain, json, github annotations, or sarif (for GitHub code scanning).

See ARCHITECTURE.md for the full pipeline and CONTRIBUTING.md to add a rule or extractor in one file.

Why mcpxray

• Static, not runtime. No need to start the server or trust what it reports at runtime — parse definitions from source. Deterministic and CI-safe.
• MCP-semantic. Knows about tool poisoning, schema compatibility, over-permissive tools — things generic SAST and OpenSSF Scorecard can't see.
• Source-level locations. Findings point at file:line, not anonymous runtime entries.
• Plugin-friendly. Add a rule or an extractor by subclassing + one decorator. Entry-points let external packages extend mcpxray without forking.

Dogfood

Scanned against the official modelcontextprotocol/python-sdk example servers:

(FastMCP's framework-injected ctx: Context parameter is correctly excluded from every tool's schema — the same way the SDK itself does it — so it doesn't generate noise.)

Roadmap

• v0.2 — scope URL clones to the server entry point, TypeScript static extractor, rules MCP105/109, opt-in runtime tools/list capture (--runtime --command). ✅ shipped.
• v1.0 — frozen plugin API (SemVer), --fix/--diff, pre-commit hook, GitHub Actions CI, PyPI trusted publishing. ✅ shipped (v1.0.0).
• Later (needs external services/accounts): hosted badge API + leaderboard (hosting), registry integrations (Glama/Smithery API keys). Full history: docs/v0.2-plan.md.

License

MIT.