内容
# charles-mcp
一个 [MCP](https://modelcontextprotocol.io) 服务器（使用Rust编写），允许AI代理驱动 [Charles Proxy 5](https://www.charlesproxy.com/) 并检查其HTTP(S)流量 — 记录、限制、切换工具，并列出/搜索/读取/ **重放** 请求，请求体解码（gzip/brotli/base64，protobuf/gRPC，WebSocket）并以JSON格式美化输出。适用于实时会话或保存的 `.har` / `.chlsj` / `.chls` 文件。流量被一次性摄入嵌入式SQLite存储（FTS5搜索 + 内容寻址体去重），因此在大型会话中保持快速。
## 设置
1. 在Charles中：启用 **代理 → 网络接口设置**。
2. 安装预编译的二进制文件（macOS arm64/intel，Linux x64）：
```bash
curl -fsSL https://raw.githubusercontent.com/cbxss/charles-mcp/main/install.sh | sh
```
…或从源代码编译：`cargo build --release`（捆绑SQLite，需要C编译器）。
3. 在您的MCP客户端中注册：
```bash
claude mcp add charles -- ~/.local/bin/charles-mcp
```
默认假设Charles运行在 `127.0.0.1:8888`。运行 **`charles_status`** 首先。如果没有Charles？将 `read_session_file` 指向保存的 `.har` / `.chlsj` / `.chls` 文件。
## 工具
**控制：** `charles_status` · `start_recording` · `stop_recording` · `set_throttling` · `get_throttling` · `set_tool` · `get_tool_status` · `write_interception_rules` · `clear_session` · `quit_charles` · `reset_store`
**检查：** `list_requests` · `get_request` · `search_traffic` · `get_session_stats` · `replay_request` · `export_session` · `read_session_file` · `get_websocket_messages`
- **`list_requests`** 按优先级排序，并为每行标记资源类别。按主机/方法/状态/ MIME类型/资源类别/最小优先级/路径正则过滤，或 `only_new: true` 表示实时跟踪。
- **`search_traffic`** 是对URL、头部和解码正文的FTS5搜索；`regex: true` 表示正文正则扫描。
- **`replay_request`** 将捕获的请求重新发送到其源（主机固定为捕获的主机）。需要 `confirm: true`，以及 `allow_mutating: true` 表示POST/PUT/PATCH/DELETE。
- **`write_interception_rules`** 编写Charles本地设置XML，适用于映射本地、映射远程和重写规则。使用 `enable_tools: true` 立即启用相应的Charles引擎。使用 `save_to_charles_config: true` 和 `confirm: true` 将规则备份并合并到Charles的持久化配置中。
- 破坏性工具 — `clear_session`, `quit_charles`, `reset_store`, 和 `set_tool(breakpoints, enable)` — 需要 `confirm: true`。
## 拦截规则
Charles的网络接口可以切换映射本地、映射远程和重写，但它不公开实时的CRUD操作。`write_interception_rules` 通过生成Charles设置XML并可选地将其保存到Charles配置文件中来处理此问题。
典型流程：
1. 调用 `write_interception_rules` 并带有 `map_local`, `map_remote`, 和/或 `rewrite_sets`。
2. 如果Charles应立即启用相应的引擎，则设置 `enable_tools: true`。
3. 设置 `save_to_charles_config: true` 和 `confirm: true`，以在进行时间戳备份后将规则合并到Charles配置中。
保存的配置规则需要Charles重启或重新加载后才能在实时流量中使用新定义。如果您只需要手动导入的文件，请将 `save_to_charles_config` 设置为false，并使用 **工具 → 导入/导出设置** 导入生成的XML。
## 配置
每个标志都有一个 `CHARLES_*` 环境变量备用；运行 `--help` 获取完整列表。常见标志：
| 标志 | 默认值 | |
| --- | --- | --- |
| `--proxy-host` / `--proxy-port` | `127.0.0.1` / `8888` | Charles代理 |
| `--web-user` / `--web-pass` | _(无)_ | 网络接口基本身份验证 |
| `--db-path` | _(无)_ | 持久化存储（默认：内存中） |
| `--charles-config-path` | 平台默认 | `write_interception_rules(save_to_charles_config)` 使用的配置文件 |
对于命名protobuf/gRPC解码，请为每个调用传递一个 `.proto` 文件：`get_request(index, proto_file="/abs/path/api.proto", proto_type="pkg.Msg")`。`proto_type` 可以是短名称或完全限定的名称，如果文件定义单个消息，则可以省略；`proto_root` 设置导入 `.proto` 文件的根目录（默认为文件目录）。相同的参数适用于 `get_websocket_messages` 获取二进制帧。
## 连接方式
网络接口不是一个普通端口 — 它通过代理在神奇的主机 `control.charles` 上访问：
```
charles-mcp ──HTTP──▶ Charles 代理 (127.0.0.1:8888) ──内部──▶ control.charles
```
## 注意事项
- **HTTPS需要SSL代理** 在Charles中针对每个主机启用，否则请求保持为不透明的CONNECT隧道（标记为此类，而不是伪装为空）。
- **`set_tool` 仅为主开关** — 使用 `write_interception_rules` 获取映射本地/映射远程/重写定义。`breakpoints` 仍然挂起匹配流量，等待Charles GUI（因此需要 `confirm`）。
- **实时读取会拉取整个会话** 每次 `--cache-ttl-ms` 刷新（Charles没有增量API）；服务器自己的 `control.charles` 流量被丢弃，以保持存储的精简。
- `.chlsj` 架构、解码器和实时端点都基于真实的Charles 5捕获。
