MCP- watchdog
项目介绍
🛡️ MCP-Watchdog
<p align="center"> <strong>MCP（模型上下文协议）通信实时异常检测</strong> </p> <p align="center"> <img src="https://img.shields.io/badge/状态-测试版-yellow" alt="测试版状态"> <img src="https://img.shields.io/badge/生产-不可用-red" alt="不可用于生产"> </p> <p align="center"> <a href="#概述">概述</a> • <a href="#背景">背景</a> • <a href="#特性">特性</a> • <a href="#安装">安装</a> • <a href="#使用">使用</a> • <a href="#贡献">贡献</a> </p>⚠️ 重要通知
MCP-Watchdog 目前处于测试版状态，不适合用于生产环境。 此工具：
- 🧪 实验性质且正在积极开发中
- 🐛 可能存在错误和意外行为
- 📊 尚未在所有环境中进行全面测试
- 🔄 可能会未经通知地进行重大更改
请自行承担风险，仅在开发/测试环境中使用。不要依赖此工具对生产系统中的关键安全监控。
🎯 概述
MCP-Watchdog 是一个轻量级的安全监控工具，它捕获并分析 Claude Desktop 和 MCP 服务器之间的通信，实现实时异常模式检测，无需复杂的策略定义。
📖 背景
虽然存在多种 MCP 流量监控工具，但大多数依赖于预定义策略和基于关键词的敏感信息监控。然而，“敏感信息”的定义在不同行业和组织之间差异很大，使得通用检测规则不足。
传统的数据防泄漏（DLP）方法需要：
- 📋 对业务工作流进行广泛的映射
- 🔍 识别所有敏感数据类型
- ⚙️ 创建和维护自定义策略
- ⏱️ 投入大量时间和精力
MCP-Watchdog 采取了不同的方法：它不依赖预定义规则，而是从合法用户的学习正常使用模式，并根据行为偏差检测异常。这是首次尝试将异常检测应用于 MCP 流量。
✨ 特性
- 🚀 零配置异常检测 - 不需要定义敏感数据模式
- 📊 自动基线学习 - 学习您的正常使用模式
- ⚡ 实时监控 - 对可疑活动即时警报
- 🎨 颜色编码警报 - 易读的严重程度指示器
- 📝 全面日志记录 - 所有检测的完整审计跟踪
- 🔄 透明代理 - 不影响 Claude Desktop 功能
🔧 系统需求
- Python 3.8+
- Windows 10/11
- Node.js（用于 npx）
- Claude Desktop
📦 安装
# 克隆仓库
git clone https://github.com/yourusername/MCP-Watchdog.git
cd MCP-Watchdog
# 安装依赖
pip install -r requirements.txt
🔧 代理配置
MCP-Watchdog 使用基于主题的异常检测方法。检测器从合法使用中学习正常的主题模式，并将主要包含新/未知主题的请求标记为异常。它使用简单的词袋方法，具有可配置的灵敏度，需要少量训练数据（10-20个会话）来建立基线。
了解代理设置
MCP-Watchdog 通过拦截 Claude Desktop 和 MCP 服务器之间的通信来工作。它通过插入一个透明代理 (mcp_proxy.py) 来实现这一点：
- 捕获所有 MCP 协议消息
- 记录它们以供分析
- 不变地转发它们以维持功能
配置过程
setup_proxy.py 脚本会自动修改您的 Claude Desktop 配置，使其通过代理路由流量：
之前（原始配置）：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem"]
}
}
}
之后（带有 MCP-Watchdog 代理）：
{
"mcpServers": {
"filesystem": {
"command": "python",
"args": [
"C:\\path\\to\\MCP-Watchdog\\mcp_proxy.py",
"filesystem",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem"
]
}
}
}
设置命令
# 标准设置
python setup_proxy.py
# 带管理员权限设置（如果出现权限错误）
python setup_proxy.py --admin
# 从备份恢复原始配置
python setup_proxy.py --restore
# 移除代理配置（重置到原始）
python setup_proxy.py --reset
配置文件位置
- Windows：
%APPDATA%\Claude\claude_desktop_config.json - 备份：
%APPDATA%\Claude\claude_desktop_config.backup
代理设置故障排除
<details> <summary><b>❌ “配置文件可能无法写入”</b></summary>以管理员权限运行：
python setup_proxy.py --admin
- 完全关闭 Claude Desktop
- 检查任务管理器是否有任何
Claude.exe进程 - 再次运行设置
- 验证代理是否在配置中：检查
claude_desktop_config.json - 重启 Claude Desktop
- 检查代理日志：
type mcp_proxy_minimal.log - 确保 Python 在 PATH 中：
python --version
要完全移除 MCP-Watchdog 并恢复原始配置：
# 选项 1：重置配置
python setup_proxy.py --reset
# 选项 2：从备份恢复
python setup_proxy.py --restore
手动配置（高级）
如果自动设置失败，您可以手动编辑配置：
- 关闭 Claude Desktop
- 打开
%APPDATA%\Claude\claude_desktop_config.json - 对每个 MCP 服务器，包装命令：
- 将
"command": "npx"更改为"command": "python" - 在 args 前添加：
["C:\\path\\to\\mcp_proxy.py", "server_name", "npx"]
- 将
- 保存并重新启动 Claude Desktop
🚀 快速开始
1️⃣ 配置代理
python setup_proxy.py
这将：
- 备份当前配置
- 插入监控代理到所有 MCP 服务器
- 验证配置是否正确更新
⚠️ 重要：配置期间必须关闭 Claude Desktop
2️⃣ 收集正常使用数据
重要：在构建基线之前，您需要收集正常使用的数据。
-
重启 Claude Desktop 后配置代理
-
正常使用 Claude 几个会话：
- 与各种 MCP 工具交互
- 执行典型的工作流程
- 使用不同的特性和命令
- 使用越多样化的功能，基线越好
-
验证数据收集：
# 检查是否捕获了数据 dir mcp_captured_data\ # 查看代理日志 type mcp_proxy_minimal.log | more您应该看到类似会话目录：
session_20250723_143022_filesystem/ session_20250723_145512_brave-search/ session_20250723_150234_memory/ -
实时捕获监控（可选）：
# 实时查看捕获的数据 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: 客户支持指南...
🚨 异常检测
============================================================
🔴 检测到异常 - 高严重性
============================================================
时间: 2025-07-23 14:23:46
工具: API-post-search
查询: 数据库密码重置
置信度: 100.0%
新主题: 数据库, 密码, 重置
预期: 客户, 支持, 服务
============================================================
📁 项目结构
MCP-Watchdog/
├── 🔌 mcp_proxy.py # 通信拦截器
├── 🧠 mcp_anomaly_detector.py # 基于机器学习的检测引擎
├── 📊 mcp_baseline_builder.py # 模式学习工具
├── 👁️ realtime_monitor.py # 实时监控界面
├── ⚙️ setup_proxy.py # 自动配置脚本
├── 📂 mcp_captured_data/ # 会话日志
│ └── session_*/ # 单个会话
│ ├── requests.jsonl # 捕获的请求
│ └── responses.jsonl # 捕获的响应
├── 📄 mcp_proxy_minimal.log # 代理操作日志
├── 🔐 mcp_baseline.pkl # 训练好的基线模型
└── 📋 anomaly_log_*.json # 检测到的异常
🎛️ 配置
调整检测灵敏度
# 更严格的检测
detector = SimpleTopicAnomalyDetector(sensitivity=0.9)
# 更宽松
detector = SimpleTopicAnomalyDetector(sensitivity=0.5)
🐛 故障排除
<details> <summary><b>没有捕获数据</b></summary>- 确保已配置代理：
python setup_proxy.py - 完全重启 Claude Desktop
- 检查代理日志：
type mcp_proxy_minimal.log - 验证
mcp_captured_data目录是否存在
- 最小推荐：10-20 个会话
- 在收集过程中使用各种 MCP 工具
- 检查数据质量：
python mcp_baseline_builder.py - 构建器将显示收集数据的统计信息
- 退出 Claude Desktop
- 终止 Python：
taskkill /F /IM python.exe - 重新启动 Claude Desktop
- 降低灵敏度设置
- 使用更多数据重建基线
- 将模式添加到白名单
🔒 安全注意事项
- 🔐 捕获的数据可能包含敏感信息
- 🛡️ 保护
mcp_captured_data目录 - 📋 定期审查异常日志
- ⚠️ 测试版软件 - 不推荐用于生产安全监控
- 🧪 在隔离环境中彻底测试后再广泛部署
🗺️ 发展路线图
当前检测方法
MCP-Watchdog 目前使用一种简单的基于主题的异常检测方法，识别 MCP 请求中的不寻常词汇。虽然对于基本监控有效，但这种方法存在局限性。
计划改进
增强检测算法
- N-gram 模式分析：捕捉短语级别的模式，而不仅仅是单独的单词
- 序列异常检测：识别不寻常的命令序列和时间模式
- 上下文分析：考虑连续请求之间的关系
- 高级机器学习模型：
- 使用孤立森林进行离群值检测
- 使用自动编码器进行复杂模式学习
- 使用 LSTM 网络进行时间序列分析
- 行为档案：用户特定的基线和每种工具的阈值
系统功能
- 🌐 带实时可视化功能的网络仪表板
- 📧 多渠道警报（电子邮件、Slack、Discord、短信）
- 📊 统计分析和报告
- 🔄 从确认的误报中持续学习
- ⚡ 自动响应动作（阻止、警报、记录）
- 🔍 事件调查的取证分析工具
- 🎯 规则基础检测以补充机器学习方法
- 📈 性能指标和检测准确率追踪
集成与部署
- Docker 容器化
- 云部署选项（AWS、Azure、GCP）
- 与 SIEM 系统集成
- 用于外部集成的 REST API
- 多操作系统支持（macOS、Linux）
🤝 贡献
欢迎贡献！请注意，这是一个测试版项目：
- 🐛 欢迎提交错误报告和修复
- 💡 功能建议应考虑其实验性质
- 🧪 所有贡献应包括适当的测试
- 📝 更新文档以反映任何更改
请打开一个议题讨论重大更改。
📄 许可
MIT 许可
💬 支持
发现错误？有问题？请 打开一个议题。
<p align="center"> 为 MCP 社区制作 ❤️ </p>