使用说明

🛡️ MCPSec

MCP的安全门楣

一个MCP服务器，用于审核其他MCP服务器是否符合 MCP官方规范, OWASP MCP前10名, OWASP 代理 AI 前十名，以及 FastMCP安全基线。扫描任何服务器。获取合规报告。解决问题。

部分 MCP鲨鱼项目族 --用于模型上下文协议的取证分析、安全扫描和开发工具。

MCP鲨鱼产品	用途
智能扫描	基于人工智能的安全分析和风险评估
检查员	实时MCP流量监控与调试
MCPSec	对MCP规范和OWASP标准进行深入的合规性扫描

为什么选择MCPSec

模型上下文协议正迅速成为将AI代理连接到工具的通用标准，被Claude、ChatGPT、VS Code、Gemini和Cursor采用。但MCP安全是事后才考虑的：

88% MCP服务器需要凭据，但是 53% 依赖不安全的静态秘密
仅 8.5% 实现现代OAuth身份验证
30个CVE 6周内记录在案，其中43%为exec/shell注入
针对MCP客户端的第一个完整RCE（CVE-2025-6514）得分 CVSS 9.6
无现有工具 系统地验证是否符合官方MCP规范

MCPSec填补了这一空白。

主要特点

34项安全调查结果 6名审计员（身份验证、传输、授权、工具、配置、供应链）
4种检测模式 --端点探测、MCP自检、主动令牌测试、静态分析
LLM混合分类器 --基于规则的第一轮+LLM语义分析（BYOK通过LiteLLM）
合规记分卡 --MCP规范、OWASP MCP前10名、FastMCP基线评分A-F级
双界面 --作为MCP服务器（用于Claude Desktop、Cursor、VS Code）或独立CLI运行
4种报告格式 --Markdown、JSON、SARIF（GitHub代码扫描）、交互式HTML仪表板
CI/CD门控 — mcpsec ci 根据CVSS阈值返回退出代码
扫描历史记录 --带扫描比较和趋势跟踪的SQLite存储
直通LLM --在MCP服务器模式下，使用客户端自己的LLM进行分类
隐私第一 --完全本地，没有数据离开您的机器

快速开始

安装

pip install mcpsharksec

首次扫描

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

LLM分类

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

生成报告

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服务器模式

MCPSec本身就是一个MCP服务器——任何MCP客户端都可以直接调用其扫描工具。

启动服务器

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

克劳德桌面版

添加 claude_desktop_config.json:

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

从源代码（不安装pip）：

{
  "mcpServers": {
    "mcpsec": {
      "command": "/path/to/mcpsec/.venv/bin/python",
      "args": ["-m", "mcpsec.cli", "serve"],
      "cwd": "/path/to/mcpsec"
    }
  }
}

克劳德代码

Claude Code使用自己的CLI来管理MCP服务器：

# 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/mcp.json:

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

VS Code

添加 .vscode/settings.json:

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

双子星命令行工具

添加 ~/.gemini/settings.json （全球）或 .gemini/settings.json （项目）：

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

或者使用Gemini CLI命令：

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

ChatGPT

ChatGPT需要 远程HTTPS端点 --它无法连接到本地stdio服务器。要将MCPSec与ChatGPT一起使用：

在公共HTTPS URL上部署带有流式HTTP的MCPSec（或使用类似ngrok的隧道进行测试）
启用 开发者模式 在ChatGPT设置中（需要Pro、Team、Enterprise或Edu计划）
首选 设置→ 应用程序和连接器→ 创建
输入您的MCPSec服务器URL（例如。 https://your-server.com/mcp)

注：建议仅在本地使用安全扫描。ChatGPT集成最适合团队/企业部署（见路线图M6）。

直通LLM流量

在MCP服务器模式下，MCPSec不需要自己的LLM API密钥。相反：

客户电话 scan_tools(url) → 获取基于规则的发现
客户电话 get_unclassified_tools(url) → 获取预先构建的分类提示
这 客户自己的法学硕士 提示的原因
客户电话 classify_tools(scan_id, classifications) → 并入调查结果

这意味着Claude Desktop使用Claude，Cursor使用其配置的模型，Gemini CLI使用Gemini等。--自动。

CLI参考

命令	描述
`mcpsec scan <url>`	全面安全扫描（所有审计员）
`mcpsec auth <url>`	OAuth 2.1合规性审计
`mcpsec transport <url>`	传输和会话安全
`mcpsec authorization <url>`	范围和权限模型审核
`mcpsec tools <url>`	工具元数据和中毒分析
`mcpsec config [path]`	本地配置文件审核
`mcpsec dependencies <path>`	依赖性漏洞检查
`mcpsec ci <url> --fail-on 7.0`	CI/CD模式（CVSS阈值上的退出代码）
`mcpsec serve`	以MCP服务器运行
`mcpsec report <scan_id>`	生成合规报告
`mcpsec list`	列出以前的扫描
`mcpsec compare <id_a> <id_b>`	比较两次扫描
`mcpsec scan_local`	枚举和审核本地MCP服务器（存根）

通用标志

--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 → 推荐→ Fix

MCPSec遵循三层架构：

第1层：扫描✅

无损探测、配置分析、工具元数据检查、与FastMCP身份验证基线的模式匹配。

第2级：推荐✅

对于每个发现：解释风险，映射到特定的规范部分+OWASP ID，提供FastMCP代码示例的逐步补救。

第3层：修复（路线图）

自动生成可供编码代理（Claude Code、Cursor、Copilot）使用的结构化修复描述符。MCPSec输出修复程序——开发人员的编码代理应用它们。

调查结果目录

MCPSec检测 34项安全调查结果 6名审计员：

身份验证（从AUTH-001到AUTH-013）

ID	标题	严重性	检测
AUTH-001	受保护的资源元数据丢失	严重	端点
AUTH-002	检测到令牌通过	严重	静态
AUTH-003	未强制执行令牌访问群体绑定	严重	活动
AUTH-004	通过HTTP的远程服务器（无TLS）	严重	端点
AUTH-005	不支持PKCE	严重	端点
AUTH-006	授权服务器元数据缺失	高	端点
AUTH-007	未强制执行资源指示符	高	活动
AUTH-008	URI查询字符串中的承载令牌	高	端点
AUTH-009	401缺少WWW身份验证标头	高	端点
AUTH-010	作用域错误处理不足	中等	活动
AUTH-011	WWW身份验证挑战中没有作用域	中等	端点
AUTH-012	无注册机制	介质	端点
AUTH-013	带HTTP身份验证的STDIO服务器	低	端点

运输（TRANS-001至TRANS-004）

ID	标题	严重性	检测
TRANS-001	弃用的SSE传输	高	端点
TRANS-002	SSRF易受攻击的元数据URL	关键	端点
TRANS-003	会话ID低熵	高	活动
TRANS-004	会话绑定未强制执行	高	活动

授权（AUTHZ-001至AUTHZ-004）

ID	标题	严重性	检测
AUTHZ-001	未经授权的管理工具	严重	活动
AUTHZ-002	无每工具范围要求	高	反思
AUTHZ-003	通配符/宽范围定义	高	内省
AUTHZ-004	通过作用域提升权限	严重	活动

工具（工具-001至工具-005）

ID	标题	严重性	检测
TOOL-001	工具描述中毒	严重	内省+LLM
TOOL-002	指令注入模式	临界	静态
TOOL-003	路径遍历漏洞	高	静态
TOOL-004	输入模式缺少约束	高	自省
TOOL-005	危险工具名称	高	内省+LLM

配置（CONFIG-001至CONFIG-004）

ID	标题	严重性	检测
CONFIG-001	配置中的硬编码凭据	关键	静态
CONFIG-002	启动程序中的外壳注入	临界	静态
CONFIG-003	服务器路径上的Symlink攻击	高	静态
CONFIG-004	检测到影子MCP服务器	高	静态

供应链（SC-001至SC-004）

ID	标题	严重性	检测
SC-001	依赖关系中的已知CVE	严重	静态
SC-002	检测到百草枯包装	严重	静态
SC-003	无固定依赖版本	中等	静态
SC-004	未经验证的包发布器	中等	静态

合规记分卡

每次扫描都会生成一个合规性记分卡：

总分（0-100） 字母等级A-F
MCP规范合规性 --根据官方MCP授权规范得分
OWASP MCP十大覆盖范围 --明确0-10个风险类别
FastMCP基线 --与FastMCP的身份验证实现模式保持一致

随着 --llm 启用后，记分卡包括人工智能生成的 风险叙述 解释发现交互作用和优先补救推理。

LLM混合分类

MCPSec使用双通道检测管道：

基于规则 （快速、自由、确定性）——用于中毒、危险名称、模式问题的正则表达式模式
LLM语义分析 （选择加入）——捕捉规则遗漏的微妙操纵

支持的提供商（BYOK）

提供者	环境变量	默认模型
人类学	`ANTHROPIC_API_KEY`	claude-sonnet-4-20250514
OpenAI	`OPENAI_API_KEY`	gpt-4o
谷歌 `GEMINI_API_KEY`	双子座2.0闪光
米斯特拉尔	`MISTRAL_API_KEY`	mistral大最新
Groq	`GROQ_API_KEY`	骆驼-3.3-70b

从环境变量中自动检测到。覆盖 --model 或 MCPSEC_LLM_MODEL.

报告

标记语言

终端友好，是GitHub PR评论的理想选择。

JSON

机器可读，可与其他工具集成。

萨里夫

GitHub代码扫描、Azure DevOps、VS代码SARIF查看器的标准格式。

HTML仪表盘

交互式网络安全主题仪表板，包括：

严重程度圆环图
OWASP MCP十大雷达图
框架合规性柱状图
可排序/可过滤的发现，具有可扩展的详细信息
补救优先级表

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

CI/CD集成

GitHub 操作

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

这 mcpsec ci 如果任何发现达到或超过CVSS阈值，则命令以代码1退出。

标准与合规框架

MCPSec根据以下内容进行验证：

标准	覆盖范围
MCP规范（草案-2025-11-25）	OAuth 2.1、传输、会话、输入验证
FastMCP身份验证基线	TokenVerifier、OAuthProvider、require_scopes（）、restrict_tag（）
OWASP MCP前10名（v0.12025）	所有10个风险类别
OWASP 代理 AI 前十名（2026）	ASI01–ASI10交叉引用
OWASP LLM Top 10 （2025）	MCP特定变体
RFC	6749, 6750, 7591, 7636, 8414, 8707, 9728
NIST AI RMF	风险管理交叉引用
米特地图集	对抗性机器学习技术映射

建筑

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

发展

设置

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

运行测试

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

测试覆盖率

444测试 涵盖所有6名审核员、LLM分类器、记分卡、报告
用于主动检查验证的合规+不合规测试服务器
用于确定性LLM测试的MockProvider
具有真实人类分类的实时LLM测试

竞争比较

能力	Snyk	MintMCP	MCPScan.ai	MCPShield	代理审计	MCPSec
MCP规范合规性审计	❌	❌	❌	❌	❌	✅
FastMCP身份验证基线	❌	❌	❌	❌	❌	✅
OAuth 2.1验证	❌	❌	部分	❌	❌	✅
OWASP MCP Top 10全覆盖	部分	部分	局部	局部	部分	✅
工具中毒（LLM）	✅	✅	✅	❌	✅	✅
供应链扫描	❌	❌	❌	✅	✅	✅
SSRF端点扫描	❌	❌	❌	❌	❌	✅
修正+代码示例	❌	❌	❌	❌	❌	✅
合规记分卡	❌	❌	❌	❌	❌	✅
扫描比较/趋势分析	❌	❌	❌	❌	❌	✅
交互式HTML仪表板	❌	❌	❌	❌	❌	✅
CI/CD集成	✅	❌	❌	✅	❌	✅
MCP服务器模式	❌	❌	❌	❌	❌	✅
隐私（完全本地）	❌	❌	❌	✅	❌	✅

路线图

里程碑	范围	状态
M1	核心扫描仪、16项发现、CLI、报告	✅ 完成
平方米	所有34个发现、LLM分类器、测试服务器、记分卡、HTML报告	✅ 完成
立方米	公开发布、PyPI包、5+客户端测试、文档	🔄 进行中
M4	自动修复生成（第3层）、结构化修复描述符、npm包装器、GitHub Action	已计划
M5	代理扫描程序（独立的MCP服务器，OWASP代理AI Top 10）	计划中
M6	企业（远程部署、团队仪表板、策略引擎）	已计划

分布

渠道	里程碑	状态
PyPI — `pip install mcpsharksec`	M3	✅ 已发布
npm — `npm install mcpsharksec`	M4	计划中
GitHub行动 — `mcp-shark/mcpsec-action@v1`	M4	计划中

许可证

麻省理工学院——见许可证.

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