MCTS

Model Context Threat Scanner

Security analysis purpose-built for Model Context Protocol (MCP) servers — permissions, injection, attack chains, and risk scoring.

Make MCP threat scanning as easy as running a linter.

mcts scan ./server.py

Demo

Scan the included vulnerable MCP server:

uv run mcts scan examples/vulnerable-mcp-server/server.py

$ mcts scan examples/vulnerable-mcp-server/server.py
[✓] Discovering tools...
[✓] Mapping permissions...
[✓] Detecting attack chains...
[✓] Generating report...

==================== MCTS Security Report ====================
Overall Score:   5/100 (CRITICAL)
Risk Index:      100/100
Scoring basis:   3 Critical, 7 High, 2 Medium (12 scorable findings)
Formula:         3×25 + 7×10 + 2×3 = 151 → round(100 × e^(-151/50)) = 5

Severity Summary          Top Findings
● Critical    4           [1] CRITICAL Destructive tool: delete_all_users
● High        7           [2] CRITICAL Read → exfiltration attack chain possible
● Medium      2           ...

Tip: Record a terminal GIF of the scan above and add it here as docs/assets/scan-demo.gif for maximum README impact.

Problem

MCP servers expose databases, APIs, file systems, cloud resources, and SaaS tools to AI agents — often without rigorous security review. MCTS helps teams find issues before attackers do.

Features

Quick Start

Prerequisites

• Python 3.11+
• uv (recommended)

Install

git clone https://github.com/MCP-Audit/MCTS.git
cd MCTS
uv sync --all-extras

Scan an MCP server

uv run mcts scan examples/vulnerable-mcp-server/server.py

Save JSON and generate an executive HTML dashboard:

uv run mcts scan examples/vulnerable-mcp-server/server.py -o report.json
uv run mcts report report.json -o security-report.html
open security-report.html

The HTML report includes a dark-themed overview (score gauge, letter grade, severity cards, posture summary), risk breakdown with radar chart, searchable findings, attack chain graph, OWASP mapping, and in-browser export (JSON / HTML / PDF). See docs/html-report.md.

CI gate (fail on critical or score)

uv run mcts scan ./server.py --fail-on-critical --min-score 70
uv run mcts scan ./server.py -o report.sarif --format sarif

See docs/ci-integration.md and action/README.md.

Themes

uv run mcts scan ./server.py --theme cyber    # default
uv run mcts scan ./server.py --theme minimal --no-progress

Architecture

  MCP server (file / repo / config)
              │
              ▼
     Discovery (static Py+TS, optional live stdio)
              │
              ▼
     19 security analyzers + compliance + MCTS-T taxonomy
              │
              ▼
        Risk scoring engine
              │
    ┌─────────┼─────────┐
    ▼         ▼         ▼
 Terminal   JSON/     HTML dashboard
 dashboard  SARIF    (mcts report)

Documentation

• Getting Started
• CLI Reference
• Architecture
• Live Scanning · Fuzzing · Inventory
• Scoring Spec · CI Integration
• Threat Taxonomy · TypeScript Discovery
• HTML Security Dashboard
• Feature Expansion Plan · Roadmap
• Changelog

Project Structure

MCTS/
├── src/mcts/          # Main package (src layout)
│   ├── cli/             # Typer CLI (`scan`, `report`, `inventory`, `fuzz`)
│   ├── core/            # Scanner orchestration, ScanConfig
│   ├── discovery/       # Static (Python/TS), live stdio, merge
│   ├── probe/           # Live session, consent, behavioral events
│   ├── analyzers/       # 19+ security analyzers
│   ├── inventory/       # Client config discovery
│   ├── fuzz/            # Protocol fuzz runner
│   ├── taxonomy/        # MCTS-T techniques, Sigma rules
│   ├── scoring/         # Risk scoring engine
│   ├── compliance/      # OWASP & MCP compliance checks
│   ├── reporting/       # ScanReport models, SARIF, HTML entry
│   ├── report/          # HTML dashboard (templates, CSS, JS)
│   ├── ui/              # Terminal dashboard (Rich)
│   └── mcp/             # MCPServerInfo models
├── tests/               # pytest suite + regression fixtures
├── examples/            # Sample MCP servers & benchmarks
├── action/              # GitHub Action (`@v1`)
└── docs/                # Documentation

Development

uv sync --all-extras
uv run pytest
uv run ruff check src tests
uv run ruff format src tests
pre-commit install

Positioning

Roadmap

Next up: SSE/HTTP transports, mcts audit-config, scan history/trends, mcts pentest agent. Phase 0–1 foundation (repo scan, SARIF, live probe, inventory, taxonomy) is shipped — see Roadmap.

Contributing

See CONTRIBUTING.md.

License

Apache License 2.0 — see LICENSE.

Security

To report vulnerabilities, see SECURITY.md.