🛡️ 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](https://www.mcpshark.sh/) project family — forensic analysis, security scanning, and developer tooling for the Model Context Protocol.

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):

{
  "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

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)

Transport (TRANS-001 to TRANS-004)

Authorization (AUTHZ-001 to AUTHZ-004)

Tools (TOOL-001 to TOOL-005)

Configuration (CONFIG-001 to CONFIG-004)

Supply Chain (SC-001 to SC-004)

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)

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:

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

Roadmap

Distribution

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>