MCPSec

🛡️ MCPSec

The security linter for MCP

    

An MCP server that audits other MCP servers for compliance with the official MCP specification, OWASP MCP Top 10, OWASP Agentic AI Top 10, and the FastMCP security baseline. Scan any server. Get a compliance report. Fix issues.

Part of the MCP Shark project family — forensic analysis, security scanning, and developer tooling for the Model Context Protocol.

| MCP Shark Product | Purpose | |---|---| | Smart Scan | AI-powered security analysis & risk assessment | | Inspector | Real-time MCP traffic monitoring & debugging | | MCPSec | Deep compliance scanning against MCP spec & OWASP standards |

---

Why MCPSec

The Model Context Protocol is rapidly becoming the universal standard for connecting AI agents to tools — adopted by Claude, ChatGPT, VS Code, Gemini, and Cursor. But MCP security is an afterthought:

• 88% of MCP servers require credentials, but 53% rely on insecure static secrets
• Only 8.5% implement modern OAuth authentication
• 30 CVEs documented in 6 weeks, with 43% being exec/shell injection
• The first full RCE against an MCP client (CVE-2025-6514) scored CVSS 9.6
• No existing tool systematically validates compliance against the official MCP spec

MCPSec fills this gap.

---

Key Features

• 34 security findings across 6 auditors (auth, transport, authorization, tools, config, supply chain)
• 4 detection modes — endpoint probing, MCP introspection, active token testing, static analysis
• LLM hybrid classifier — rule-based first pass + LLM semantic analysis (BYOK via LiteLLM)
• Compliance scorecard — MCP Spec, OWASP MCP Top 10, FastMCP baseline scores with A–F grading
• Dual interface — runs as an MCP server (for Claude Desktop, Cursor, VS Code) or standalone CLI
• 4 report formats — Markdown, JSON, SARIF (GitHub Code Scanning), interactive HTML dashboard
• CI/CD gating — mcpsec ci returns exit codes based on CVSS thresholds
• Scan history — SQLite storage with scan comparison and trend tracking
• Passthrough LLM — in MCP server mode, uses the client's own LLM for classification
• Privacy-first — fully local, no data leaves your machine

---

Quick Start

Install

pip install mcpsharksec

First Scan

mcpsec scan https://your-mcp-server.com

With LLM Classification

export ANTHROPIC_API_KEY=sk-...   # or OPENAI_API_KEY, GEMINI_API_KEY
mcpsec scan https://your-mcp-server.com --llm

Generate Reports

mcpsec report <scan_id> --format html      # Interactive dashboard
mcpsec report <scan_id> --format markdown   # Terminal / GitHub PR
mcpsec report <scan_id> --format sarif      # GitHub Code Scanning

---

MCP Server Mode

MCPSec is itself an MCP server — any MCP client can invoke its scanning tools directly.

Start the Server

mcpsec serve                              # stdio (Claude Desktop, Cursor, Claude Code)
mcpsec serve --transport http --port 8000  # Streamable HTTP

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mcpsec": {
      "command": "mcpsec",
      "args": ["serve"]
    }
  }
}

From source (without pip install): ``json { "mcpServers": { "mcpsec": { "command": "/path/to/mcpsec/.venv/bin/python", "args": ["-m", "mcpsec.cli", "serve"], "cwd": "/path/to/mcpsec" } } } ``

Claude Code

Claude Code uses its own CLI to manage MCP servers:

# Add MCPSec (installed via pip)
claude mcp add-json mcpsec '{"command":"mcpsec","args":["serve"]}'

# Or from source
claude mcp add-json mcpsec '{"command":"/path/to/mcpsec/.venv/bin/python","args":["-m","mcpsec.cli","serve"],"cwd":"/path/to/mcpsec"}'

# Use --scope to control availability
claude mcp add-json mcpsec --scope user '{"command":"mcpsec","args":["serve"]}'
# Scopes: local (default, current project), project (shared via .mcp.json), user (all projects)

# Manage servers
claude mcp list
claude mcp get mcpsec
claude mcp remove mcpsec

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "mcpsec": {
      "command": "mcpsec",
      "args": ["serve"]
    }
  }
}

VS Code

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "mcpsec": {
        "command": "mcpsec",
        "args": ["serve"]
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project):

{
  "mcpServers": {
    "mcpsec": {
      "command": "mcpsec",
      "args": ["serve"]
    }
  }
}

Or use the Gemini CLI command:

gemini mcp add --transport stdio mcpsec -- mcpsec serve

ChatGPT

ChatGPT requires a remote HTTPS endpoint — it cannot connect to local stdio servers. To use MCPSec with ChatGPT:

1. Deploy MCPSec with Streamable HTTP on a public HTTPS URL (or use a tunnel like ngrok for testing)
2. Enable Developer Mode in ChatGPT settings (requires Pro, Team, Enterprise, or Edu plan)
3. Go to Settings → Apps & Connectors → Create
4. Enter your MCPSec server URL (e.g. https://your-server.com/mcp)

Note: Local-only usage is recommended for security scanning. ChatGPT integration is best suited for team/enterprise deployments (see Roadmap M6).

Passthrough LLM Flow

In MCP server mode, MCPSec doesn't need its own LLM API key. Instead:

1. Client calls scan_tools(url) → gets rule-based findings
2. Client calls get_unclassified_tools(url) → gets pre-built classification prompts
3. The client's own LLM reasons over the prompts
4. Client calls classify_tools(scan_id, classifications) → merged into findings

This means Claude Desktop uses Claude, Cursor uses its configured model, Gemini CLI uses Gemini, etc. — automatically.

---

CLI Reference

| Command | Description | |---|---| | mcpsec scan <url> | Full security scan (all auditors) | | mcpsec auth <url> | OAuth 2.1 compliance audit | | mcpsec transport <url> | Transport & session security | | mcpsec authorization <url> | Scope & permission model audit | | mcpsec tools <url> | Tool metadata & poisoning analysis | | mcpsec config [path] | Local config file audit | | mcpsec dependencies <path> | Dependency vulnerability check | | mcpsec ci <url> --fail-on 7.0 | CI/CD mode (exit code on CVSS threshold) | | mcpsec serve | Run as MCP server | | mcpsec report <scan_id> | Generate compliance report | | mcpsec list | List previous scans | | mcpsec compare <id_a> <id_b> | Compare two scans | | mcpsec scan_local | Enumerate & audit local MCP servers (stub) |

Common Flags

--access remote|authenticated|local    # Scanner access level
--depth quick|standard|thorough        # Scan thoroughness
--test-token <token>                   # Bearer token for active checks
--llm                                  # Enable LLM classification (BYOK)
--model <name>                         # Override LLM model
--json                                 # Output as JSON

---

Scan → Recommend → Fix

MCPSec follows a three-tier architecture:

Tier 1: Scan ✅

Non-destructive probing, configuration analysis, tool metadata inspection, pattern matching against the FastMCP auth baseline.

Tier 2: Recommend ✅

For each finding: explains the risk, maps to specific spec sections + OWASP IDs, provides step-by-step remediation with FastMCP code examples.

Tier 3: Fix (Roadmap)

Auto-generate structured fix descriptors consumable by coding agents (Claude Code, Cursor, Copilot). MCPSec outputs fixes — the developer's coding agent applies them.

---

Findings Catalog

MCPSec detects 34 security findings across 6 auditors:

Authentication (AUTH-001 to AUTH-013)

| ID | Title | Severity | Detection | |---|---|---|---| | AUTH-001 | Protected Resource Metadata Missing | Critical | Endpoint | | AUTH-002 | Token Passthrough Detected | Critical | Static | | AUTH-003 | Token Audience Binding Not Enforced | Critical | Active | | AUTH-004 | Remote Server Over HTTP (No TLS) | Critical | Endpoint | | AUTH-005 | PKCE Not Supported | Critical | Endpoint | | AUTH-006 | Authorization Server Metadata Missing | High | Endpoint | | AUTH-007 | Resource Indicator Not Enforced | High | Active | | AUTH-008 | Bearer Token in URI Query String | High | Endpoint | | AUTH-009 | 401 Missing WWW-Authenticate Header | High | Endpoint | | AUTH-010 | Insufficient Scope Error Handling | Medium | Active | | AUTH-011 | No Scope in WWW-Authenticate Challenge | Medium | Endpoint | | AUTH-012 | No Registration Mechanism | Medium | Endpoint | | AUTH-013 | STDIO Server with HTTP Auth | Low | Endpoint |

Transport (TRANS-001 to TRANS-004)

| ID | Title | Severity | Detection | |---|---|---|---| | TRANS-001 | Deprecated SSE Transport | High | Endpoint | | TRANS-002 | SSRF-Vulnerable Metadata URL | Critical | Endpoint | | TRANS-003 | Session ID Low Entropy | High | Active | | TRANS-004 | Session Binding Not Enforced | High | Active |

Authorization (AUTHZ-001 to AUTHZ-004)

| ID | Title | Severity | Detection | |---|---|---|---| | AUTHZ-001 | Admin Tool Without Authorization | Critical | Active | | AUTHZ-002 | No Per-Tool Scope Requirements | High | Introspection | | AUTHZ-003 | Wildcard/Broad Scope Definitions | High | Introspection | | AUTHZ-004 | Privilege Escalation via Scope | Critical | Active |

Tools (TOOL-001 to TOOL-005)

| ID | Title | Severity | Detection | |---|---|---|---| | TOOL-001 | Tool Description Poisoning | Critical | Introspection + LLM | | TOOL-002 | Command Injection Pattern | Critical | Static | | TOOL-003 | Path Traversal Vulnerability | High | Static | | TOOL-004 | Input Schema Missing Constraints | High | Introspection | | TOOL-005 | Dangerous Tool Name | High | Introspection + LLM |

Configuration (CONFIG-001 to CONFIG-004)

| ID | Title | Severity | Detection | |---|---|---|---| | CONFIG-001 | Hardcoded Credentials in Config | Critical | Static | | CONFIG-002 | Shell Injection in Startup Args | Critical | Static | | CONFIG-003 | Symlink Attack on Server Path | High | Static | | CONFIG-004 | Shadow MCP Server Detected | High | Static |

Supply Chain (SC-001 to SC-004)

| ID | Title | Severity | Detection | |---|---|---|---| | SC-001 | Known CVE in Dependency | Critical | Static | | SC-002 | Typosquat Package Detected | Critical | Static | | SC-003 | Unpinned Dependency Version | Medium | Static | | SC-004 | Unverified Package Publisher | Medium | Static |

---

Compliance Scorecard

Every scan produces a compliance scorecard:

• Overall Score (0–100) with letter grade A–F
• MCP Spec Compliance — scored against official MCP authorization spec
• OWASP MCP Top 10 Coverage — 0–10 risk categories clear
• FastMCP Baseline — alignment with FastMCP's auth implementation patterns

With --llm enabled, the scorecard includes an AI-generated risk narrative explaining finding interactions and prioritized remediation reasoning.

---

LLM Hybrid Classification

MCPSec uses a two-pass detection pipeline:

1. Rule-based (fast, free, deterministic) — regex patterns for poisoning, dangerous names, schema issues
2. LLM semantic analysis (opt-in) — catches subtle manipulation that rules miss

Supported Providers (BYOK)

| Provider | Env Variable | Default Model | |---|---|---| | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-20250514 | | OpenAI | OPENAI_API_KEY | gpt-4o | | Google | GEMINI_API_KEY | gemini-2.0-flash | | Mistral | MISTRAL_API_KEY | mistral-large-latest | | Groq | GROQ_API_KEY | llama-3.3-70b |

Auto-detected from environment variables. Override with --model or MCPSEC_LLM_MODEL.

---

Reports

Markdown

Terminal-friendly, ideal for GitHub PR comments.

JSON

Machine-readable, for integration with other tools.

SARIF

Standard format for GitHub Code Scanning, Azure DevOps, VS Code SARIF Viewer.

HTML Dashboard

Interactive cybersecurity-themed dashboard with:

• Severity donut chart
• OWASP MCP Top 10 radar chart
• Framework compliance bar chart
• Sortable/filterable findings with expandable details
• Remediation priorities table

mcpsec scan https://mcp-server.com
mcpsec report <scan_id> --format html
# Opens mcpsec_report_<scan_id>.html

---

CI/CD Integration

GitHub Actions

name: MCP Security Scan
on: [push, pull_request]

jobs:
  mcpsec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mcpsharksec
      - run: mcpsec ci ${{ vars.MCP_SERVER_URL }} --fail-on 7.0 --json

The mcpsec ci command exits with code 1 if any finding meets or exceeds the CVSS threshold.

---

Standards & Compliance Framework

MCPSec validates against:

| Standard | Coverage | |---|---| | MCP Specification (draft-2025-11-25) | OAuth 2.1, transport, session, input validation | | FastMCP Auth Baseline | TokenVerifier, OAuthProvider, require_scopes(), restrict_tag() | | OWASP MCP Top 10 (v0.1, 2025) | All 10 risk categories | | OWASP Agentic AI Top 10 (2026) | ASI01–ASI10 cross-referenced | | OWASP LLM Top 10 (2025) | MCP-specific variants | | RFCs | 6749, 6750, 7591, 7636, 8414, 8707, 9728 | | NIST AI RMF | Risk management cross-references | | MITRE ATLAS | Adversarial ML technique mapping |

---

Architecture

graph TB
    subgraph Target["Target MCP Server"]
        T[MCP Server being scanned]
    end

    subgraph Engine["Scanner Engine"]
        A1[Auth Auditor<br/>AUTH-001 to 013]
        A2[Transport Auditor<br/>TRANS-001 to 004]
        A3[Authorization Auditor<br/>AUTHZ-001 to 004]
        A4[Tools Auditor<br/>TOOL-001 to 005]
        A5[Config Auditor<br/>CONFIG-001 to 004]
        A6[Supply Chain Auditor<br/>SC-001 to 004]
        LLM[LLM Hybrid Classifier<br/>Rule-based + Semantic]
    end

    subgraph Reports["Results & Reports"]
        SC[Compliance Scorecard]
        MD[Markdown]
        HTML[HTML Dashboard]
        SARIF[SARIF]
        JSON[JSON]
        DB[(SQLite History)]
    end

    subgraph Server["MCPSec Server - FastMCP"]
        MCP[14 MCP Tools<br/>Streamable HTTP / stdio]
        CLI[CLI + CI/CD]
    end

    subgraph Clients["MCP Clients"]
        CD[Claude Desktop]
        CC[Claude Code]
        VS[VS Code]
        CU[Cursor]
        GE[Gemini CLI]
        GP[ChatGPT]
        CI[CI/CD Pipelines]
    end

    T --> Engine
    A4 --> LLM
    Engine --> Reports
    Reports --> Server
    Server --> Clients

    style Target fill:#1a1a2e,stroke:#ff1744,color:#fff
    style Engine fill:#0f1729,stroke:#448aff,color:#fff
    style Reports fill:#0f1729,stroke:#69f0ae,color:#fff
    style Server fill:#0f1729,stroke:#ffd600,color:#fff
    style Clients fill:#111827,stroke:#c0c8d8,color:#fff

---

Development

Setup

git clone https://github.com/mcp-shark/mcpsec.git
cd mcpsec
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run Tests

pytest -m "not llm and not exa" -v     # Core tests (no API keys needed)
pytest -v                               # Full suite (needs ANTHROPIC_API_KEY)
pytest -m exa -v                        # Real-world Exa MCP server tests

Test Coverage

• 444 tests covering all 6 auditors, LLM classifier, scorecard, reports
• Compliant + non-compliant test servers for active check validation
• MockProvider for deterministic LLM testing
• Live LLM tests with real Anthropic classification

---

Competitive Comparison

| Capability | Snyk | MintMCP | MCPScan.ai | MCPShield | AgentAudit | MCPSec | |---|---|---|---|---|---|---| | MCP Spec compliance audit | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | FastMCP auth baseline | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | OAuth 2.1 verification | ❌ | ❌ | Partial | ❌ | ❌ | ✅ | | OWASP MCP Top 10 full coverage | Partial | Partial | Partial | Partial | Partial | ✅ | | Tool poisoning (LLM) | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | | Supply chain scanning | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | | SSRF endpoint scanning | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Remediation + code examples | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Compliance scorecard | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Scan comparison / trending | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Interactive HTML dashboard | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | CI/CD integration | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | | MCP server mode | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Privacy (fully local) | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ |

---

Roadmap

| Milestone | Scope | Status | |---|---|---| | M1 | Core scanner, 16 findings, CLI, reports | ✅ Complete | | M2 | All 34 findings, LLM classifier, test servers, scorecard, HTML reports | ✅ Complete | | M3 | Public release, PyPI package, 5+ client testing, documentation | 🔄 In Progress | | M4 | Auto-fix generation (Tier 3), structured fix descriptors, npm wrapper, GitHub Action | Planned | | M5 | Agent Scanner (separate MCP server, OWASP Agentic AI Top 10) | Planned | | M6 | Enterprise (remote deployment, team dashboards, policy engine) | Planned |

Distribution

| Channel | Milestone | Status | |---|---|---| | PyPI — pip install mcpsharksec | M3 | ✅ Published | | npm — npm install mcpsharksec | M4 | Planned | | GitHub Action — mcp-shark/mcpsec-action@v1 | M4 | Planned |

---

License

MIT — see LICENSE.

---

<p align="center"> <a href="https://www.mcpshark.sh/"> <strong>Part of the MCP Shark project family</strong> </a> <br/> <em>Forensic analysis, security scanning, and developer tooling for the Model Context Protocol</em> </p>