异常检测工具

🛡️ MCP监视器

Real-time Anomaly Detection for MCP (Model Context Protocol) Communications

Overview • Background • Features • Installation • Usage • Contributing

⚠️ 重要通知

MCP监视器目前处于测试状态，不适合生产使用。 此工具是：

• 🧪 正在进行实验和积极开发
• 🐛 可能包含错误和意外行为
• 📊 未在所有环境中进行彻底测试
• 🔄 如有重大变更，恕不另行通知

使用风险自负 并且仅在开发/测试环境中。不要依赖此工具进行生产系统中的关键安全监控。

🎯 概述

MCP监视器是一个轻量级的安全监控工具，可以捕获和分析Claude Desktop和MCP服务器之间的通信，实时检测异常模式，而不需要复杂的策略定义。

📖 背景

虽然存在几种MCP流量监控工具，但大多数都依赖于预定义的策略和基于关键字的检测来监控敏感信息。然而，“敏感信息”的定义在不同行业和组织之间差异很大，使得通用检测规则不足。

传统的DLP（数据丢失防护）方法要求：

• 📋 业务工作流程的广泛映射
• 🔍 识别所有敏感数据类型
• ⚙️ 自定义策略创建和维护
• ⏱️ 投入大量时间和精力

MCP监视器采取了不同的方法：它不是预定义的规则，而是从合法用户那里学习正常的使用模式，并根据行为偏差检测异常。这是第一次将异常检测应用于MCP流量的已知尝试。

✨ 特性

• 🚀 零配置异常检测 -无需定义敏感数据模式
• 📊 自动基线学习 -从您的正常使用模式中学习
• ⚡ 实时监控 -可疑活动的即时警报
• 🎨 颜色编码警报 -易于阅读的严重性指标
• 📝 综合录井 -所有检测的完整审计跟踪
• 🔄 透明代理 -对Claude Desktop功能没有影响

🔧 系统要求

• Python 3.8+
• Windows 10/11
• Node.js（适用于npx）
• 克劳德桌面

📦 安装

# Clone the repository
git clone https://github.com/yourusername/MCP-Watchdog.git
cd MCP-Watchdog

# Install dependencies
pip install -r requirements.txt

🔧 代理配置

MCP监视器使用基于主题的异常检测方法。检测器从合法使用中学习正常的主题模式，并将主要包含新/未知主题的请求标记为异常。它使用一种简单的词袋方法，具有可配置的灵敏度，需要最少的训练数据（10-20个会话）来建立基线。

了解代理设置

MCP监视器通过拦截Claude Desktop和MCP服务器之间的通信来工作。它通过插入透明代理来实现这一点(mcp_proxy.py)即：

• 捕获所有MCP协议消息
• 记录它们以供分析
• 原封不动地转发它们以保持功能

配置过程

这 setup_proxy.py 脚本会自动修改您的Claude Desktop配置，以通过代理路由流量：

之前（原始配置）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

之后（使用MCP监视器代理）：

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": [
        "C:\\path\\to\\MCP-Watchdog\\mcp_proxy.py",
        "filesystem",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem"
      ]
    }
  }
}

设置命令

# Standard setup
python setup_proxy.py

# Setup with administrator privileges (if permission errors)
python setup_proxy.py --admin

# Restore original configuration from backup
python setup_proxy.py --restore

# Remove proxy configuration (reset to original)
python setup_proxy.py --reset

配置文件位置

• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• 备份: %APPDATA%\Claude\claude_desktop_config.backup

代理设置故障排除

python setup_proxy.py --admin

# Option 1: Reset configuration
python setup_proxy.py --reset

# Option 2: Restore from backup
python setup_proxy.py --restore

手动配置（高级）

如果自动设置失败，您可以手动编辑配置：

1. 关闭克劳德桌面
2. 打开 %APPDATA%\Claude\claude_desktop_config.json
3. 对于每个MCP服务器，包装以下命令：
   • 改变 "command": "npx" 向 "command": "python"
   • args的前缀： ["C:\\path\\to\\mcp_proxy.py", "server_name", "npx"]
4. 保存并重新启动Claude Desktop

🚀 快速开始

1.️⃣ 配置代理

python setup_proxy.py

这将：

• 备份当前配置
• 为所有MCP服务器插入监控代理
• 验证配置是否已正确更新

⚠️ 重要：配置期间必须关闭Claude Desktop

2.️⃣ 收集正常使用数据

重要：在构建基线之前，您需要从正常使用中收集数据。

1. 重新启动克劳德桌面 代理配置后

2. 正常使用克劳德 对于几个会话：

   • 与各种MCP工具交互
   • 执行您的典型工作流程
   • 使用不同的功能和命令
   • 使用方式越多样化，基线就越好

3. 验证数据收集:

   复制

   # Check if data is being captured
   dir mcp_captured_data\
   
   # View proxy logs
   type mcp_proxy_minimal.log | more
   

   您应该看到以下会话目录：

   复制

   session_20250723_143022_filesystem/
   session_20250723_145512_brave-search/
   session_20250723_150234_memory/
   

4. 监控实时捕捉 （可选）：

   复制

   # Watch data being captured in real-time
   python realtime_monitor.py --capture-only
   

3.️⃣ 构建基线

一旦你收集了足够的数据（建议：至少10-20次）：

python baseline_builder.py

这将分析所有捕获的会话，并创建正常行为的基线。

4.️⃣ 开始监控

python realtime_monitor.py

现在，该系统将实时监控并对异常活动发出警报。

📊 数据收集提示

为了获得最佳的基线质量：

• 用途多样：使用不同的MCP工具和功能
• 规律：执行典型的日常工作流程
• 多个会话：目标是至少10-20次不同的会议
• 各种工具：与文件系统、搜索、数据库和其他MCP服务器交互
• 时间段：收集一天中不同时间的数据

⚠️ 备注：基线质量直接影响检测精度。更多样化和代表性的数据可以更好地检测异常。

正常活动

[14:23:45] ✅ → API-post-search: Customer Support Guidelines...

🚨 异常检测

============================================================
🔴 ANOMALY DETECTED - HIGH SEVERITY
============================================================
Time: 2025-07-23 14:23:46
Tool: API-post-search
Query: Database Password Reset
Confidence: 100.0%
New Topics: database, password, reset
Expected: customer, support, service
============================================================

📁 项目结构

MCP-Watchdog/
├── 🔌 mcp_proxy.py              # Communication interceptor
├── 🧠 mcp_anomaly_detector.py   # ML-based detection engine
├── 📊 mcp_baseline_builder.py   # Pattern learning tool
├── 👁️ realtime_monitor.py       # Live monitoring interface
├── ⚙️ setup_proxy.py            # Auto-configuration script
├── 📂 mcp_captured_data/        # Session logs
│   └── session_*/               # Individual sessions
│       ├── requests.jsonl       # Captured requests
│       └── responses.jsonl      # Captured responses
├── 📄 mcp_proxy_minimal.log     # Proxy operation log
├── 🔐 mcp_baseline.pkl          # Trained baseline model
└── 📋 anomaly_log_*.json        # Detected anomalies

🎛️ 配置

调整检测灵敏度

# Stricter detection
detector = SimpleTopicAnomalyDetector(sensitivity=0.9)

# More lenient
detector = SimpleTopicAnomalyDetector(sensitivity=0.5)

🐛 故障排除

🔒 安全说明

• 🔐 捕获的数据可能包含敏感信息
• 🛡️ 固定 mcp_captured_data 目录
• 📋 定期查看异常日志
• ⚠️ Beta软件 -不建议用于生产安全监控
• 🧪 在更广泛的部署之前，在隔离环境中进行彻底测试

🗺️ 路线图

电流检测方法

MCP监视器目前使用一种简单的基于主题的异常检测，用于识别MCP请求中的异常词汇。虽然这种方法对基本监测有效，但也有局限性。

计划改进

增强检测算法

• [ ] N-gram模式分析：捕获短语级模式，而不仅仅是单个单词
• [ ] 序列异常检测：识别异常的命令序列和时间模式
• [ ] 上下文分析：考虑连续请求之间的关系
• [ ] 高级ML模型:
  • 孤立森林用于异常检测
  • 用于复杂模式学习的自动编码器
  • 用于时间序列分析的LSTM网络
• [ ] 行为分析：用户特定的基线和每个工具的阈值

系统功能

• [ ] 🌐 具有实时可视化功能的Web仪表板
• [ ] 📧 多渠道警报（电子邮件、Slack、Discord、短信）
• [ ] 📊 统计分析和报告
• [ ] 🔄 从已验证的误报中持续学习
• [ ] ⚡ 自动响应操作（阻止、警报、日志）
• [ ] 🔍 用于事故调查的法医分析工具
• [ ] 🎯 基于规则的检测是对机器学习方法的补充
• [ ] 📈 性能指标和检测精度跟踪

集成与部署

• []Docker容器化
• []云部署选项（AWS、Azure、GCP）
• []与SIEM系统集成
• []用于外部集成的REST API
• []支持多操作系统（macOS、Linux）

🤝 贡献

欢迎投稿！请注意，这是一个测试项目：

• 🐛 特别感谢错误报告和修复
• 💡 功能建议应考虑实验性质
• 🧪 所有贡献都应包括适当的测试
• 📝 更新文档以了解任何更改

请打开一个问题来讨论重大更改。

📄 许可证

MIT许可证

💬 支持

发现bug了吗？有问题吗？请 打开一个问题.

Made with ❤️ for the MCP community