Skip to content

mcp-shark/MCPSec

BranchesTags

Repository files navigation

🛡️ MCPSec

The security linter for MCP

PyPI CI Python 3.12+ License MCP Shark

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

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

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.

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

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v0.1.1 — README & packaging updates Latest
Feb 27, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages