Sharkmcp

🚀 SharkMCP - 网络数据包分析MCP服务器

SharkMCP是一个模型上下文协议（MCP）服务器，它通过集成Wireshark/tshark，提供网络数据包捕获和分析功能。该服务器专为AI助手进行网络安全分析、故障排除和数据包检查而设计。

该服务器适用于需要让代理调试发送请求的程序并验证数据包流量的场景，支持以下工作流程：

• 开始记录数据包
• 运行工具或执行请求
• 停止记录并分析结果

🚀 快速开始

前提条件

系统要求

• Wireshark/tshark：必须安装且可访问。
• Node.js：版本18+。
• pnpm：包管理器（推荐）。

安装Wireshark/tshark

• macOS（使用Homebrew）：

brew install wireshark

• Ubuntu/Debian：

sudo apt update
sudo apt install tshark wireshark-common

• Windows：从 wireshark.org 下载。

安装步骤

1. 克隆仓库：

git clone https://github.com/kriztalz/SharkMCP.git
cd SharkMCP

2. 安装依赖：

pnpm install

3. 构建项目：

pnpm run build

4. 运行服务器：

pnpm start

✨ 主要特性

• 异步数据包捕获：可使用可配置的过滤器和超时时间启动后台捕获会话。
• PCAP文件分析：能够分析现有的数据包捕获文件。
• 灵活的输出格式：支持JSON、自定义字段或传统文本输出。
• SSL/TLS解密：支持使用SSL密钥日志文件解密HTTPS流量。
• 可重复使用的配置：可以保存和重复使用捕获/分析配置。

⚠️ 重要提示

数据包信息可能非常庞大。请确保使用范围显示过滤器，以免使对话上下文过载。

📦 安装指南

克隆仓库

git clone https://github.com/kriztalz/SharkMCP.git
cd SharkMCP

安装依赖

pnpm install

构建项目

pnpm run build

运行服务器

pnpm start

💻 使用示例

可用工具

1. start_capture_session：启动后台数据包捕获。
2. stop_capture_session：停止捕获并分析结果。
3. analyze_pcap_file：分析现有的PCAP文件。
4. manage_config：保存/加载可重复使用的配置。

基础用法

启动捕获会话

接口: en0
捕获过滤器: port 443
超时时间: 30 秒

分析捕获的流量

显示过滤器: tls.handshake.type == 1
输出格式: json

保存配置

{
  "name": "https-monitoring",
  "description": "监控HTTPS流量",
  "captureFilter": "port 443",
  "displayFilter": "tls.handshake.type == 1",
  "outputFormat": "json",
  "timeout": 60,
  "interface": "en0"
}

📚 详细文档

架构

SharkMCP提供了一个简单的、专注于本地开发的架构：

┌─────────────────────────────────────────────────────────┐
│                    SharkMCP Server                      │
├─────────────────────────────────────────────────────────┤
│  MCP协议层                                              │
│  ├─ start_capture_session                               │
│  ├─ stop_capture_session                                │
│  ├─ analyze_pcap_file                                   │
│  └─ manage_config                                       │
├─────────────────────────────────────────────────────────┤
│  tshark集成层                                           │
│  ├─ 跨平台可执行文件检测                                │
│  ├─ 进程管理                                            │
│  └─ 输出解析 (JSON/字段/文本)                            │
├─────────────────────────────────────────────────────────┤
│  主机系统集成                                          │
│  ├─ 本地tshark安装                                      │
│  ├─ 直接网络接口访问                                    │
│  └─ 原生文件系统操作                                    │
└─────────────────────────────────────────────────────────┘

配置

MCP客户端设置

{
  "mcpServers": {
    "sharkmcp": {
      "command": "node",
      "args": ["/path/to/SharkMCP/dist/index.js"]
    }
  }
}

SSL/TLS解密（可选）

要解密HTTPS流量，需导出 SSLKEYLOGFILE 环境变量：

export SSLKEYLOGFILE=/path/to/sslkeylog.log

然后配置应用程序将SSL密钥记录到该文件。当设置了环境变量时，许多应用程序会自动支持此功能。 最后，在 stop_capture_session 工具中将日志文件路径名传递给MCP服务器。

测试

SharkMCP包含全面的集成测试，用于验证数据包捕获功能。

运行测试

# 运行所有测试
pnpm test

开发

项目结构

SharkMCP/
├── src/
│   ├── index.ts              # 主服务器设置
│   ├── types.ts              # TypeScript接口
│   ├── utils.ts              # 实用函数
│   └── tools/                # 单个工具实现
│       ├── start-capture-session.ts
│       ├── stop-capture-session.ts
│       ├── analyze-pcap-file.ts
│       └── manage-config.ts
├── test/                     # 测试文件
│   └── integration.test.js   # 集成测试
├── package.json
└── README.md

开发命令

# 开发模式，自动重新加载
pnpm run dev

# 生产环境构建
pnpm run build

# 运行测试
pnpm run test

# 类型检查
pnpm run build

安全注意事项

• 网络权限：数据包捕获需要提升的权限。
• 文件访问：临时文件会在 /tmp/ 中创建。
• Docker安全：容器以非root用户运行。
• SSL密钥日志：敏感的SSL密钥应安全处理。

故障排除

常见问题

• “tshark not found”：
  • 确保Wireshark已安装，且tshark在PATH中。
  • 使用 tshark -v 检查安装情况。
• 数据包捕获权限被拒绝：
  • 在Linux上：将用户添加到 wireshark 组或使用 sudo 运行。
  • 在macOS上：在系统偏好设置中授予终端网络访问权限。
  • 在Windows上：以管理员身份运行。
• 未捕获到数据包：
  • 验证网络接口名称（Linux上使用 ip link，macOS上使用 ifconfig）。
  • 检查捕获过滤器语法。
  • 确保接口上有流量。

🔧 技术细节

SharkMCP通过集成Wireshark/tshark实现网络数据包的捕获和分析。其架构分为MCP协议层、tshark集成层和主机系统集成层。MCP协议层提供了启动和停止捕获会话、分析PCAP文件以及管理配置等功能。tshark集成层负责跨平台可执行文件检测、进程管理和输出解析。主机系统集成层则处理本地tshark安装、直接网络接口访问和原生文件系统操作。通过这种分层架构，SharkMCP能够在不同的操作系统上稳定运行，并提供灵活的数据包分析功能。

📄 许可证

本项目采用MIT许可证。

贡献

非常欢迎大家为项目做出贡献！贡献步骤如下：

1. 分叉仓库。
2. 创建功能分支。
3. 按照现有代码风格进行更改。
4. 为新功能添加测试。
5. 提交拉取请求。

问题与建议

如果您有任何问题或建议，请随时创建一个issue。