snapspecter/mitmproxy-mcp
GitHub: snapspecter/mitmproxy-mcp
基于 MCP 协议封装 mitmproxy 的服务器，使 AI 智能体能实时检查、拦截、修改和重放 HTTP/HTTPS 流量，服务于安全测试、API 逆向工程和自动化调试场景。
Stars: 10 | Forks: 4
# mitmproxy MCP 服务器
一个模型上下文协议（MCP）服务器，可将 mitmproxy 转换为适用于 AI 智能体的强大工具集。这允许 LLM（如 Claude、GPT-4 或本地模型）实时检查、修改和重放 HTTP/HTTPS 流量。
## 本次构建的新增功能（有趣的部分）
该项目已超越了简单的捕获与重放。您现在可以：
* **快速搜索流量**，支持按域名/方法/正文文本进行过滤。
* **从响应中提取数据**，使用 JSONPath 或 CSS 选择器。
* **使用会话变量**，从某个响应中获取 token 并在后续的重放中复用它们。
* **运行轻量级模糊测试**，针对查询参数或 JSON 正文字段进行快速的 DAST 检查。
* **重构 API 模式**，并从捕获的流量中导出 OpenAPI 风格的规范。
* **检测身份验证模式**（Bearer/JWT/API key/session cookie/CSRF/OAuth 提示）。
* **从真实的捕获流中生成基础爬虫代码**。
## 为什么要使用它？
标准的“网络搜索”或“获取”工具是无状态的，并且很容易被检测到。mitmproxy-mcp 提供：
* **深度调试**：智能体可以检查完整的请求/响应周期（请求头、负载、cookies），以识别前端崩溃的原因或 API 返回 `4xx/500` 错误的原因。
* **API 逆向工程**：让 LLM 观察未公开的内部 API，梳理出 JSON schema，并自动生成客户端库或文档。
* **自动化安全测试**：通过允许智能体将负载注入特定参数并分析响应，来执行 DAST（动态应用安全测试）。
* **实时拦截**：动态修改流量：注入请求头、模拟响应以供测试或拦截跟踪像素以减少噪音。
* **隐蔽重放**：使用 `curl-cffi` 模仿 Chrome/Safari 的 TLS 指纹，绕过标准 Python 库会触发的基本反机器人措施。
## 核心功能
- **生命周期控制**：直接从 LLM 启动和停止 mitmproxy 实例。
- **深度检查**：捕获完整的请求/响应周期，包括请求头、正文和时间。
- **流量搜索与过滤**：按域名限定范围，然后按查询/方法搜索流，以保持上下文整洁。
- **主动拦截**：通过动态规则注入请求头、使用正则表达式替换正文内容或拦截请求。
- **隐蔽重放**：使用 `curl-cffi` 重新执行流，以模拟现代浏览器的 TLS 指纹（例如 Chrome）。
- **会话感知工作流**：提取动态值（如 CSRF token）并将其重新注入重放的流量中。
- **响应数据提取**：通过 CSS 选择器和 JSONPath 从 HTML/JSON 响应中提取结构化值。
- **API 发现**：将相似的端点进行分组，识别路径/查询参数，并导出 OpenAPI JSON。
- **安全侦察助手**：检测常见的身份验证模式并运行有针对性的模糊测试负载。
- **爬虫引导**：从观察到的流量生成可执行的 `curl-cffi` 自动化代码。
## 快速开始
### 选项 1：使用 `uvx`（推荐）
将此内容添加到您的 MCP 客户端配置中（例如 Claude Desktop、Cursor 或 AntiGravity）：
```
{
"mcpServers": {
"mitmproxy-mcp": {
"command": "uvx",
"args": ["mitmproxy-mcp"]
}
}
}
```
### 选项 2：从克隆的仓库运行
如果您想从本地克隆运行（适用于开发或测试未发布的更改）：
```
git clone https://github.com/snapspecter/mitmproxy-mcp.git
```
然后将此内容添加到您的 MCP 客户端配置中，并将路径替换为您的克隆位置：
```
{
"mcpServers": {
"mitmproxy-mcp": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "/path/to/mitmproxy-mcp", "mitmproxy-mcp"]
}
}
}
```
## 安装
### 选项 1：全局安装（使用 `uv`）
```
uv tool install mitmproxy-mcp
```
### 选项 2：Docker（隔离环境）
```
# 构建并运行
docker build -t mitmproxy-mcp .
docker run -p 8080:8080 mitmproxy-mcp
```
### 选项 3：手动 Pip 安装
```
python -m venv venv
source venv/bin/activate
pip install mitmproxy-mcp
```
## 可用工具
### 生命周期与配置
* `start_proxy(port=8080)`：启动 mitmproxy 服务器。
* `stop_proxy()`：关闭代理。
* `set_scope(allowed_domains)`：过滤记录的流量（例如 `["api.github.com", "example.com"]`）。
* `list_tools()`：返回所有暴露的 MCP 工具和输入 schema。
### 检查
* `get_traffic_summary(limit=20)`：返回最近的网络流列表。
* `inspect_flow(flow_id)`：提供特定流的完整详细信息和等效的 `curl` 命令。
* `search_traffic(query, domain, method, limit=50)`：按关键字/域名/方法过滤捕获的流量。
* `clear_traffic()`：清除已保存的流量历史。
### 修改与拦截
* `add_interception_rule(rule_id, action_type, ...)`：
* `action_type`：`inject_header`、`replace_body` 或 `block`。
* `phase`：`request` 或 `response`。
* `set_global_header(key, value)`：向每个请求注入一个请求头。
* `remove_global_header(key)`：移除先前注入的全局请求头。
* `list_rules()`：显示当前活动的拦截规则。
* `clear_rules()`：清空所有活动的拦截规则。
### 重放
* `replay_flow(flow_id, method, headers_json, body)`：使用浏览器级别的模拟，通过修改后的参数重新发送请求。
### 提取与会话变量
* `extract_from_flow(flow_id, json_path=None, css_selector=None)`：从捕获的响应正文中提取值。
* `set_session_variable(name, value)`：手动设置会话变量。
* `extract_session_variable(name, flow_id, regex_pattern, group_index=1)`：从响应正文中提取并保存变量。
### 安全与 API 分析
* `fuzz_endpoint(flow_id, target_param, param_type, payload_category, timeout=10.0)`：通过负载替换进行重放并报告异常。
* `get_api_patterns(domain=None, limit=50)`：将捕获的流量聚类为端点模式。
* `export_openapi_spec(domain=None, limit=50)`：从捕获的流量生成 OpenAPI v3 JSON 规范。
* `detect_auth_pattern(flow_ids=None)`：从观察到的请求中推断可能的身份验证机制。
### 代码生成
* `generate_scraper_code(flow_ids, target_framework="curl_cffi")`：从捕获的流中生成基础的爬虫/自动化代码。
## 编程式使用
注意：这些是由 MCP 主机（客户端）发送的 JSON-RPC 调用。您无需在终端中手动输入这些内容。
1. **初始化代理**：
`{"method": "tools/call", "params": {"name": "start_proxy", "arguments": {"port": 8080}}}`
2. **拦截与屏蔽**：
`{"method": "tools/call", "params": {"name": "add_interception_rule", "arguments": {"rule_id": "block-ads", "action_type": "block", "url_pattern": ".*analytics.*"}}}`
3. **修改响应**：
`{"method": "tools/call", "params": {"name": "add_interception_rule", "arguments": {"rule_id": "mock-api", "action_type": "replace_body", "url_pattern": ".*user/profile.*", "action_value": "{\"name\": \"AI Agent\"}"}}}`
## 实用技巧
* **管理上下文**：立即使用 `set_scope`。当充斥着后台操作系统的遥测数据时，LLM 的表现会很差。
* **浏览器设置**：确保您的浏览器或应用程序已配置为使用代理（通常是 `localhost:8080`），并已安装 mitmproxy CA 证书以便检查 HTTPS。
* **隐蔽性**：`replay_flow` 工具专门使用 `curl-cffi`，以避免被检查 TLS 指纹的服务标记为机器人。
## 开发
```
git clone [https://github.com/snapspecter/mitmproxy-mcp.git](https://github.com/snapspecter/mitmproxy-mcp.git)
cd mitmproxy-mcp
uv sync
uv run pytest
```
**许可证：** MIT
**作者：** [SnapSpecter](https://github.com/snapspecter)
标签：API安全, API逆向工程, curl-cffi, DAST, DLL 劫持, Elastic Stack, HTTP/HTTPS抓包, JSON输出, LLM工具, MCP Server, mitmproxy, Model Context Protocol, OpenAPI规范生成, Python, TLS指纹伪造, 中间人攻击, 动态应用安全测试, 反检测, 大语言模型, 态势感知, 恶意软件分析, 搜索语句（dork）, 数据提取, 无后门, 流量拦截与修改, 流量重放, 网络协议分析, 网络安全, 请求拦截, 身份验证检测, 逆向工具, 防御绕过, 隐私保护