Sharkmcp

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

一个通过集成 Wireshark/tshark 提供网络数据包捕获与分析能力的 Model Context Protocol (MCP) 服务。专为 AI 助手执行网络安全分析、故障排查和数据包检查而设计。

此服务旨在适用于你希望让 Agent 调试发送请求的程序并验证数据包流量的场景，支持以下工作流：

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

架构

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

┌─────────────────────────────────────────────────────────┐
│                    SharkMCP Server                      │
├─────────────────────────────────────────────────────────┤
│  MCP Protocol Layer                                     │
│  ├─ start_capture_session                               │
│  ├─ stop_capture_session                                │
│  ├─ analyze_pcap_file                                   │
│  └─ manage_config                                       │
├─────────────────────────────────────────────────────────┤
│  tshark Integration Layer                               │
│  ├─ Cross-platform executable detection                 │
│  ├─ Process management                                  │
│  └─ Output parsing (JSON/fields/text)                   │
├─────────────────────────────────────────────────────────┤
│  Host System Integration                                │
│  ├─ Local tshark installation                           │
│  ├─ Direct network interface access                     │
│  └─ Native file system operations                       │
└─────────────────────────────────────────────────────────┘

功能特性

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

/!\ 数据包信息可能非常庞大。请确保使用限定范围的显示过滤器，以免超出对话上下文容量。

前置条件

系统要求

• 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

测试

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

运行测试

# Run all tests
pnpm test

配置

MCP 客户端设置

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

SSL/TLS 解密（可选）

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

export SSLKEYLOGFILE=/path/to/sslkeylog.log

然后配置你的应用程序将 SSL 密钥记录到此文件。设置该环境变量后，许多应用程序会自动支持此功能。

然后将日志文件路径传递给 MCP 服务中的 stop_capture_session 工具。

使用方法

可用工具

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

基本示例

启动捕获会话：

Interface: en0
Capture Filter: port 443
Timeout: 30 seconds

分析捕获的流量：

Display Filter: tls.handshake.type == 1
Output Format: json

保存配置：

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

开发

项目结构

SharkMCP/
├── src/
│   ├── index.ts              # Main server setup
│   ├── types.ts              # TypeScript interfaces
│   ├── utils.ts              # Utility functions
│   └── tools/                # Individual tool implementations
│       ├── start-capture-session.ts
│       ├── stop-capture-session.ts
│       ├── analyze-pcap-file.ts
│       └── manage-config.ts
├── test/                     # Test files
│   └── integration.test.js   # Integration tests
├── package.json
└── README.md

开发命令

# Development mode with auto-reload
pnpm run dev

# Build for production
pnpm run build

# Run tests
pnpm run test

# Type checking
pnpm run build

安全注意事项

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

故障排查

常见问题

"tshark not found"：

• 确保已安装 Wireshark 且 tshark 在 PATH 中
• 使用以下命令检查安装：tshark -v

数据包捕获权限被拒绝：

• 在 Linux 上：将用户添加到 wireshark 组或以 sudo 运行
• 在 macOS 上：在系统偏好设置中授予终端网络访问权限
• 在 Windows 上：以管理员身份运行

未捕获到任何数据包：

• 验证网络接口名称（Linux 上使用 ip link，macOS 上使用 ifconfig）
• 检查捕获过滤器语法
• 确保接口上有流量

贡献（非常欢迎！）

1. Fork 仓库
2. 创建功能分支
3. 遵循现有代码风格进行修改
4. 为新功能添加测试
5. 提交 pull request

许可证

MIT License

问题 / 建议

如有任何问题或建议，欢迎提交 issue。