内容
# Charles MCP 服务器
[](https://pypi.org/project/charles-mcp/)
[](LICENSE)
[](https://pypi.org/project/charles-mcp/)
[文档](docs/README.md) | [工具合约](docs/contracts/tools.md) | [代理](AGENTS.md) | [代理工作流指南](docs/agent-workflows.md)
> **仓库维护通知（2026-04-21）**
> 该仓库的公共 Git 历史记录于 2026-04-21 进行重组。如果您在该日期之前克隆了此仓库，请在进行任何进一步贡献之前重新克隆。不要从较旧的本地克隆合并或推送，因为这可能会重新引入过时的历史记录。
Charles MCP 服务器连接 Charles Proxy 到 MCP 客户端，以便代理可以检查实时流量，分析保存的录音，并仅在需要时扩展个别请求。
它专注于三件事：
- 从当前的 Charles 会话中读取增量流量，同时录音仍然活跃
- 在结构化路径上保持实时和历史分析，而不是首先暴露原始转储字典
- 使用汇总优先的输出，以便代理可以在提取详细信息之前找到热点
## 当前发布方向（v3.0）
`v3.0` 方向明确：`charles-mcp` 从纯流量检查转向逆向工程工作流。
- 在现有的实时/历史分析基础上，它现在提供了一个反向分析工具界面（导入，查询，解码，回放，签名候选发现和实时反向会话）。
- 目标是让代理超越流量浏览，并围绕身份验证流程，签名，参数突变和重放性构建端到端的反向工作流。
## 快速入门
### 1. 启用 Charles Web 界面
在 Charles 中，打开：`Proxy -> Web 界面设置`
确保：
- `启用 web 界面` 被选中
- 用户名是 `admin`
- 密码是 `123456`
菜单位置：
设置对话框：
### 2. 安装和配置您的 MCP 客户端
#### 选项 A：通过 uvx（推荐）
无需克隆，无需手动虚拟环境。需要 [uv](https://docs.astral.sh/uv/getting-started/installation/)。
#### Claude Code CLI
```bash
claude mcp add-json charles '{
"type": "stdio",
"command": "uvx",
"args": ["charles-mcp"],
"env": {
"CHARLES_USER": "admin",
"CHARLES_PASS": "123456",
"CHARLES_MANAGE_LIFECYCLE": "false"
}
}'
```
#### Claude Desktop / Cursor / 通用 JSON 配置
```json
{
"mcpServers": {
"charles": {
"command": "uvx",
"args": ["charles-mcp"],
"env": {
"CHARLES_USER": "admin",
"CHARLES_PASS": "123456",
"CHARLES_MANAGE_LIFECYCLE": "false"
}
}
}
}
```
#### Codex CLI
```toml
[mcp_servers.charles]
command = "uvx"
args = ["charles-mcp"]
[mcp_servers.charles.env]
CHARLES_USER = "admin"
CHARLES_PASS = "123456"
CHARLES_MANAGE_LIFECYCLE = "false"
```
#### 选项 B：本地克隆（无 uvx）
在 uvx 不可用时使用，或者您想要编辑源代码，或者 Python 3.14 导致 stdio 传输失败（请参见下面的故障排除）。
```bash
git clone https://github.com/heizaheiza/Charles-mcp.git ~/Projects/opensource/Charles-mcp
cd ~/Projects/opensource/Charles-mcp
python3.12 -m venv .venv
.venv/bin/pip install -e "."
```
然后配置您的 MCP 客户端使用本地虚拟环境：
```json
{
"mcpServers": {
"charles": {
"type": "local",
"command": ["/path/to/Charles-mcp/.venv/bin/python", "-m", "charles_mcp"],
"environment": {
"CHARLES_USER": "admin",
"CHARLES_PASS": "123456",
"CHARLES_PROXY_HOST": "127.0.0.1",
"CHARLES_PROXY_PORT": "8888",
"CHARLES_MANAGE_LIFECYCLE": "false"
},
"enabled": true
}
}
}
```
> **Python 版本说明：** 需要 Python 3.12 或 3.13。Python 3.14 与 `mcp` 库的 stdio 传输（`anyio` 后端）存在已知不兼容性 - 服务器进程在没有响应 JSON-RPC 握手的情况下静默退出，返回代码 0。
### 通过 AI 代理自动安装
将以下提示复制并粘贴到任何 AI 代理（Claude Code、ChatGPT、Gemini CLI、Cursor Agent 等）中，它将自动安装和配置 charles-mcp：
[](#auto-install-via-ai-agent)
<details>
<summary><strong>🔴 点击展开自动安装提示（推荐）</strong></summary>
```text
安装 "charles-mcp" MCP 服务器并为我的 MCP 客户端配置它。按照以下步骤执行：
步骤 1 — 检测操作系统：
确定此机器是运行 Windows、macOS 还是 Linux。
步骤 2 — 确保 uv 已安装：
运行：uv --version
如果命令失败（uv 未找到）：
- macOS/Linux：运行：curl -LsSf https://astral.sh/uv/install.sh | sh
- Windows：运行：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
安装后，验证 uv 是否正常工作：uv --version
步骤 3 — 检测已安装的 MCP 客户端：
按以下顺序检查并使用第一个匹配项：
a) Claude Code — 运行：claude --version
如果成功，运行以下命令并跳到步骤 5：
claude mcp add-json charles '{"type":"stdio","command":"uvx","args":["charles-mcp"],"env":{"CHARLES_USER":"admin","CHARLES_PASS":"123456","CHARLES_MANAGE_LIFECYCLE":"false"}}'
b) Claude Desktop — 检查配置文件是否存在：
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows： %APPDATA%\Claude\claude_desktop_config.json
- Linux： ~/.config/Claude/claude_desktop_config.json
c) Cursor — 检查是否存在以下任意一个：
- ~/.cursor/mcp.json
- .cursor/mcp.json（在当前项目中）
d) Windsurf — 检查是否存在：
- ~/.codeium/windsurf/mcp_config.json
如果未检测到任何客户端，请询问用户使用哪个客户端。
步骤 4 — 为客户端编写配置文件（适用于 b/c/d）：
要添加的配置文件条目是:
"charles": {
"command": "uvx",
"args": ["charles-mcp"],
"env": {
"CHARLES_USER": "admin",
"CHARLES_PASS": "123456",
"CHARLES_MANAGE_LIFECYCLE": "false"
}
}
重要： 如果配置文件已经存在，请先读取它，解析 JSON，
在 "mcpServers" 中添加 "charles" 键（如果不存在则创建 "mcpServers"），
然后写回。不要覆盖其他现有的 MCP 服务器条目。
如果文件不存在，请使用以下内容创建：
{ "mcpServers": { "charles": { ... } } }
步骤 5 — 验证：
运行：uvx charles-mcp
等待 3 秒后终止进程。
如果它在没有导入错误的情况下启动，则安装成功。
步骤 6 — 报告：
打印： "charles-mcp 安装成功。请重新启动您的 MCP 客户端以加载新的服务器。"
还要提及 Charles Proxy 必须运行并启用 Web 界面（Proxy → Web 界面设置，用户名：admin，密码：123456）。
```
</details>
## 需求
- Python 3.10+
- Charles Proxy 在本地运行
- Charles Web 界面已启用
- Charles 代理监听 `127.0.0.1:8888`
`CHARLES_MANAGE_LIFECYCLE=false` 是推荐的默认值。除非您明确希望 MCP 服务器管理 Charles 生命周期，否则不要让它关闭您自己的 Charles 进程。
## 环境变量
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `CHARLES_USER` | `admin` | Charles Web 界面用户名 |
| `CHARLES_PASS` | `123456` | Charles Web 界面密码 |
| `CHARLES_PROXY_HOST` | `127.0.0.1` | Charles 代理主机 |
| `CHARLES_PROXY_PORT` | `8888` | Charles 代理端口 |
| `CHARLES_CONFIG_PATH` | 自动检测 | Charles 配置文件路径 |
| `CHARLES_REQUEST_TIMEOUT` | `10` | 控制平面 HTTP 超时（秒） |
| `CHARLES_MAX_STOPTIME` | `3600` | 最大有界录音长度 |
| `CHARLES_MANAGE_LIFECYCLE` | `false` | MCP 服务器是否管理 Charles 启动和关闭 |
| `CHARLES_REVERSE_STATE_DIR` | `${CHARLES_STATE_DIR}/reverse` | 反向分析工件和 SQLite 数据的状态根 |
| `CHARLES_VNEXT_STATE_DIR` | 旧版 | 旧版反向分析状态根。启动时，`charles-mcp` 会自动将其迁移到 `CHARLES_REVERSE_STATE_DIR` |
## 推荐流程
### 实时分析
1. `start_live_capture`
2. `group_capture_analysis`
3. `query_live_capture_entries`
4. `get_traffic_entry_detail`
5. `stop_live_capture`
此路径针对的是首先找到热点，然后深入研究确认的请求。
### 历史分析
1. `list_recordings`
2. `analyze_recorded_traffic`
3. `group_capture_analysis(source="history")`
4. `get_traffic_entry_detail`
此路径针对的是浏览保存的录音，然后深入研究选定的条目。
## 当前版本亮点（v3.0.3）
- 默认公共工具界面现已缩小到 31 个规范工具；遗留别名（`filter_func`、`proxy_by_time`、`list_sessions`）不再默认公开。
- 添加了显式兼容性切换支持：`create_server(expose_legacy_tools=True)` 或 `CHARLES_EXPOSE_LEGACY_TOOLS=true`。
- 文档入口现在汇聚到 `docs/README.md`，`docs/migrations/legacy-tools.md` 作为权威的遗留迁移指南。
- 添加了代理执行文档：根级 `AGENTS.md` 和面向任务的 `docs/agent-workflows.md`。
- 在 README 和 `docs/contracts/tools.md` 中添加了代理文档入口链接，使用仓库相对路径。
- 为高频入口工具描述添加了最小指导语义（身份保留、汇总优先、预览/读取行为），并带有合约测试以防止漂移。
- 产品方向现在明确包括逆向工程：为导入、解码、重放、签名候选发现和实时逆向工作流提供反向分析工具界面。
- `read_live_capture` 和 `peek_live_capture` 现在仅返回路由级汇总字段，例如 `host`、`method`、`path` 和 `status`，而不是原始 Charles 条目。这可以防止重复轮询扩大上下文窗口。
- `query_live_capture_entries` 现在是一条只读分析路径，不会推进实时光标。您可以在不消耗历史增量的情况下，使用相同的 `capture_id` 和不同的过滤器重复使用。
- `analyze_recorded_traffic` 和 `query_live_capture_entries` 汇总现在公开 `matched_fields` 和 `match_reasons`，以便代理可以解释请求为何被选中。
- `get_traffic_entry_detail` 现在默认为 `include_full_body=false` 和 `max_body_chars=2048`。当估计的详细负载超过约 12,000 个字符时，工具会添加一个警告，建议请求范围更窄。
- 汇总和详细输出会自动剥离 `null` 值，并隐藏内部字段，如 `header_map`、`parsed_json`、`parsed_form` 和 `lower_name`。如果需要头值，请使用 `headers` 列表。
## 工具目录
本 README 文档仅介绍推荐的工具界面。出于兼容性考虑的别名在此不做解释。
### 实时捕获工具
| 工具 | 功能 | 典型用途 |
| --- | --- | --- |
| `start_live_capture` | 启动或采用当前实时捕获并返回 `capture_id` | 在实时检查开始之前 |
| `read_live_capture` | 按光标读取增量实时条目并返回紧凑的路由摘要 | 当连续消耗新流量并且只需要主机/路径/状态时 |
| `peek_live_capture` | 预览新的实时条目而不推进光标并返回紧凑的路由摘要 | 当您想要检查新流量而不移动读取器状态时 |
| `stop_live_capture` | 停止捕获并可选地保留快照 | 当关闭或导出实时会话时 |
| `query_live_capture_entries` | 为实时捕获生成结构化汇总输出而不推进光标 | 当重复过滤当前流量中的高价值请求时 |
### 分析工具
| 工具 | 功能 | 典型用途 |
| --- | --- | --- |
| `group_capture_analysis` | 按组键聚合实时或历史流量 | 当您想要最低令牌热点视图时 |
| `get_capture_analysis_stats` | 返回粗糙的流量类别计数 | 当您想要快速分布视图时 |
| `get_traffic_entry_detail` | 加载特定条目的详细信息，并在负载太大时发出警告 | 在您已经确定目标 `entry_id` 之后 |
| `analyze_recorded_traffic` | 为保存的录音生成结构化汇总输出，并附带匹配原因 | 在分析 `.chlsj` 快照时 |
### 历史工具
| 工具 | 功能 | 典型用途 |
| --- | --- | --- |
| `list_recordings` | 列出已保存的录音文件 | 在选择历史快照之前 |
| `get_recording_snapshot` | 加载已保存录音的原始内容 | 当您需要存储的快照本身时 |
| `query_recorded_traffic` | 对最新的已保存录音应用轻量级过滤 | 当您需要快速的主机、方法或正则查询时 |
### 状态和控制工具
| 工具 | 功能 | 典型用途 |
| --- | --- | --- |
| `charles_status` | 报告 Charles 连接性和活动捕获状态 | 当检查 Charles 是否可达或捕获是否仍活动时 |
| `throttling` | 应用 Charles 网络节流预设 | 当模拟 3G、4G、5G 或禁用节流时 |
| `reset_environment` | 恢复 Charles 配置并清除当前环境 | 当您需要返回到干净的基线时 |
### 反向分析工具
| 工具名称 | 功能描述 | 典型用途 |
| --------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `reverse_import_session` | 将官方 Charles XML 或原生会话导入到规范的反向存储中 | 从保存的导出数据开始重放、解码或签名工作流 |
| `reverse_list_captures` | 列出导入的反向分析捕获数据 | 选择已经存储在反向 SQLite 平面中的捕获数据 |
| `reverse_query_entries` | 按路由字段过滤导入的反向条目 | 在详细查看或重放之前缩小候选请求集 |
| `reverse_get_entry_detail` | 返回一个导入的反向条目的规范详细信息 | 深入检查一个基准请求 |
| `reverse_decode_entry_body` | 解码存储的请求或响应体，包括带有描述符的 protobuf | 需要了解结构化有效载荷 |
| `reverse_replay_entry` | 重放一个导入的请求，可选地进行修改 | 验证请求是否可以重现或扰乱 |
| `reverse_discover_signature_candidates` | 比较多个导入的条目并排名可能的签名相关字段 | 搜索动态身份验证或签名参数 |
| `reverse_list_findings` | 列出持久化的重放和签名发现结果 | 查看之前的反向分析证据 |
| `reverse_charles_recording_status` | 报告 Charles 记录状态和反向实时会话状态 | 检查实时反向分析准备度 |
| `reverse_start_live_analysis` | 启动反向分析实时会话并通过官方导出页面快照 Charles | 需要增量跟踪新鲜流量 |
| `reverse_peek_live_entries` | 读取新的反向实时条目而不推进反向光标 | 预览新流量，然后再消费它 |
| `reverse_read_live_entries` | 读取并消费新的反向实时条目 | 推进反向实时分析会话 |
| `reverse_stop_live_analysis` | 停止反向实时分析会话，可选地恢复记录 | 清洁地关闭反向实时会话 |
| `reverse_analyze_live_login_flow` | 评估新的实时流量以确定登录/身份验证的相关性并总结下一步骤 | 跟踪登录或令牌启动流程 |
| `reverse_analyze_live_api_flow` | 评估新的实时流量以确定 API 工作流的相关性并总结下一步骤 | 跟踪结构化业务 API 流量 |
| `reverse_analyze_live_signature_flow` | 关注新的实时流量以确定签名敏感的请求和变异规划 | 针对签名、随机数或时间戳防御 |
## 关键行为
### 1. 默认返回原始值
此版本不再编辑请求或响应内容：
- 摘要、详细信息、实时和历史输出都返回原始值
- `include_sensitive` 仅为了兼容性而保留，不再更改结果
### 2. 概要优先于详细信息
首先使用 `group_capture_analysis`、`query_live_capture_entries` 或 `analyze_recorded_traffic`，然后仅在确认目标时调用 `get_traffic_entry_detail`。
除非有明确的原因，否则不要默认设置 `include_full_body=true`。
### 3. 输出针对令牌预算进行了优化
所有摘要和详细信息输出都已精简序列化：
- 内部字段如 `header_map`、`parsed_json`、`parsed_form` 和 `lower_name` 已从工具输出中排除
- `null` 值在序列化期间自动剥离
- 当详细视图中存在 `full_text` 时，会删除多余的 `preview_text`
默认参数已降低以保护上下文窗口：
| 参数 | 旧默认值 | 新默认值 |
| ---------------------- | ----------- | ----------- |
| `max_items` | 20 | 10 |
| `max_preview_chars` | 256 | 128 |
| `max_headers_per_side` | 8 | 6 |
| `max_body_chars` | 4096 | 2048 |
当需要更广泛的视图时，仍然可以显式传递更高的值。
### 4. 历史详细信息需要稳定的源标识
历史摘要返回 `recording_path`。实时摘要返回 `capture_id`。
对于 `get_traffic_entry_detail`：
- 历史记录首选 `recording_path`
- 实时首选 `capture_id`
### 5. `stop_live_capture` 失败是可恢复的
`stop_live_capture` 有两个稳定的结束状态：
- `status="stopped"` 表示捕获已实际关闭
- `status="stop_failed"` 表示短重试也失败，但捕获仍然保留
当结果为：
```json
{
"status": "stop_failed",
"recoverable": true,
"active_capture_preserved": true
}
```
捕获仍然可读，可以稍后诊断或停止。
## 开发
运行测试：
```bash
python -m pytest -q
```
有用的本地检查：
```bash
python charles-mcp-server.py
python -c "from charles_mcp.main import main; main()"
```
## 致谢
该项目最初受到 [tianhetonghua/Charles-mcp-server](https://github.com/tianhetonghua/Charles-mcp-server) 的启发，对此前的贡献表示明确的赞赏。目前，该代码库已进行了实质性的重写和重新组织，以适应不同的架构和用例，现在独立维护。
早期项目更侧重于逆向工程和安全工作流程，其功能集中在收集、关键词互锁、加密检测和任务范围的缓存管理上。本仓库针对不同的任务：使 Charles 成为客户端（如 Claude Code、Codex 和 Cursor）中稳定、低令牌、重复的 MCP 服务器，以适用于通用 AI 代理。
后续实现工作由我需要解决的具体差距驱动：
- 统一的实时捕获和历史分析模型，而不是强制代理在单独的收集和过滤思维模型之间切换
- 优先提供概要信息，按需提供详细信息，以便代理不会立即消耗大量原始数据并超出上下文窗口
- 稳定的 `capture_id`、`cursor` 和 `recording_path` 语义，以便重复查询不会意外地消耗或丢失实时流量状态
- 更严格的工具合约、恢复行为和协议一致性，以满足 AI 代理生态系统的可靠性期望
因此，本仓库已演变成一个独立的实现，适用于不同的操作模式：更结构化、更可预测、更适合于 AI 代理在实时和历史 Charles 流量中推理而无需与工具表面冲突。更简短的出处说明可在 [PROVENANCE.md](PROVENANCE.md) 中找到。
## 更新日志
### 2026-04-21（v3.0.3）
- 为修复后的公共历史版本发布做准备。
- 新增 `PROVENANCE.md` 并在两个 README 文件中缩小出处说明范围。
- 暂时从 README 文件中删除与捐赠相关的内容，以便在修复期间保持公共文档的项目焦点。
### 2026-04-15（v3.0.2）
- 严格控制默认公共接口，限缩至 31 个规范工具；旧别名现存于显式兼容层，默认隐藏。
- 新增兼容性开关：`expose_legacy_tools` 和 `CHARLES_EXPOSE_LEGACY_TOOLS`（函数参数覆盖环境变量）。
- 新增文档中心（`docs/README.md`）和旧版迁移指南（`docs/migrations/legacy-tools.md`），并统一顶级导航。
- 更新 `docs/contracts/tools.md` 以声明规范公共接口语义，并包含用于合约测试的稳定可解析 JSON 部分。
### 2026-04-14（v3.0.1）
- 新增并发布代理执行指南文档：根级 `AGENTS.md` 和 `docs/agent-workflows.md`。
- 在 README 和 `docs/contracts/tools.md` 中使用仓库相对路径为代理指南添加入口链接。
- 同步高频入口工具的最小指导提示，并添加文档/工具语义合约测试，以保持 MCP 工具描述的对齐。
### 2026-04-14（v3.0.0）
- 引入反向分析工具表面，用于导入、查询、解码、重放、签名候选发现和实时反向分析工作流程。产品范围已超越流量浏览，进入逆向工程工作流程。
- 升级实时/历史结构化分析行为：`query_live_capture_entries` 保持只读，摘要显示更清晰的匹配原因，详细信息默认保持轻量级，并有明确的大有效载荷警告。
- 文档更新至 `v3.0` 语义：两个 README 文件中的新功能部分现显示明确的版本标签。
### 2026-04-13（v2.0.2）
- 通过受信任的发布者（OIDC）为 PyPI 发布添加 GitHub Actions 发布自动化。
- 添加发布门控，带有版本/标签验证和 `twine check --strict`。
- 改进发布可见性和元数据，以便 GitHub Release 和 PyPI 发布保持一致。
### 2026-03-27（v2.0.1）
- 限制历史快照访问到托管的 `.chlsj` 文件，以便服务器不再通过录制路径输入暴露任意本地 JSON 读取。
- 修复实时分析，以便 `scan_limit` 实际被遵守，而不是在小固定扫描窗口处静默停止。
- 修复 `request_body_contains` 和 `response_body_contains`，以便匹配不再局限于剪辑预览文本。
- 将安装的运行时快照和备份移动到用户状态目录，而不是在包安装树中写入运行时数据。
- 发布 `2.0.1`，包含上述修复，并同步 GitHub 和 PyPI 上的发布。
## 参见
- [文档](docs/README.md)
- [中文 README](README.md)
- [工具合约](docs/contracts/tools.md)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器