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流量。
• 可重复使用的配置：可以保存和重复使用捕获/分析配置。

⚠️ 重要提示

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

📚 详细文档

架构

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服务器。

使用方法

可用工具

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

基本示例

启动捕获会话：

接口：en0
捕获过滤器：端口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/
├── 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未找到”：

• 确保已安装Wireshark，并且tshark在PATH中。
• 使用 tshark -v 检查安装情况。

数据包捕获权限被拒绝：

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

未捕获到数据包：

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

贡献代码（非常欢迎！）

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

📄 许可证

本项目采用MIT许可证。

问题反馈与建议

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