Charles MCP Server

Docs | Tool Contract | AGENTS | Agent Workflow Guide | English README

仓库维护公告（2026-04-21）
本仓库的公开 Git 历史已于 2026-04-21 重新整理。如果你在该日期之前克隆过本仓库，请在继续贡献前重新克隆。不要从旧的本地克隆直接合并或推送，否则可能会把过期历史重新引入仓库。

Charles MCP Server 用于把 Charles Proxy 接入 MCP 客户端，让 agent 可以稳定地读取实时流量、分析历史录包，并在需要时再展开单条请求细节。

它解决的核心问题只有三个：

录制还在进行时，agent 也能持续读取当前 session 的增量流量
live 与 history 统一走结构化分析，不再让 agent 直接消费原始抓包字典
默认使用 summary-first 输出，先看热点与摘要，再 drill-down 到单条 detail

本次更新方向（v3.0）

v3.0 的更新方向是：charles-mcp 的能力开始从“流量查看/筛选”向“逆向工程工作流”延伸。

在保留原有 live/history 分析能力的基础上，新增 reverse-analysis 工具链（导入、查询、解码、回放、签名候选分析、live 逆向会话）。
目标是让 agent 不只看到流量，还能围绕认证、签名、参数变异与可重放性，形成更完整的逆向分析闭环。

快速开始

1. 开启 Charles Web Interface

在 Charles 中依次进入：Proxy -> Web Interface Settings

请确认：

勾选 Enable web interface
用户名为 admin
密码为 123456

菜单位置示意：

设置窗口示意：

Charles Web Interface Settings

2. 安装并配置到 MCP 客户端

无需 clone 仓库，无需手动创建虚拟环境。需要先安装 uv。

Claude Code CLI

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 配置

{
  "mcpServers": {
    "charles": {
      "command": "uvx",
      "args": ["charles-mcp"],
      "env": {
        "CHARLES_USER": "admin",
        "CHARLES_PASS": "123456",
        "CHARLES_MANAGE_LIFECYCLE": "false"
      }
    }
  }
}

Codex CLI

[mcp_servers.charles]
command = "uvx"
args = ["charles-mcp"]

[mcp_servers.charles.env]
CHARLES_USER = "admin"
CHARLES_PASS = "123456"
CHARLES_MANAGE_LIFECYCLE = "false"

让 AI 自动安装

将以下提示词复制粘贴给任意 AI agent（Claude Code、ChatGPT、Gemini CLI、Cursor Agent 等），agent 会自动完成安装和配置：

Install the "charles-mcp" MCP server and configure it for my MCP client. Follow these steps exactly:

Step 1 — Detect OS:
  Determine if this machine runs Windows, macOS, or Linux.

Step 2 — Ensure uv is installed:
  Run: uv --version
  If the command fails (uv not found):
    - macOS/Linux: run: curl -LsSf https://astral.sh/uv/install.sh | sh
    - Windows: run: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  After installing, verify uv works: uv --version

Step 3 — Detect which MCP client is installed:
  Check in this order and use the FIRST match:

  a) Claude Code — run: claude --version
     If it succeeds, run this command and skip to Step 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 — check if config file exists:
     - 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 — check if any of these exist:
     - ~/.cursor/mcp.json
     - .cursor/mcp.json (in current project)

  d) Windsurf — check if exists:
     - ~/.codeium/windsurf/mcp_config.json

  If none detected, ask the user which client they use.

Step 4 — Write config (for clients b/c/d):
  The config entry to add is:
    "charles": {
      "command": "uvx",
      "args": ["charles-mcp"],
      "env": {
        "CHARLES_USER": "admin",
        "CHARLES_PASS": "123456",
        "CHARLES_MANAGE_LIFECYCLE": "false"
      }
    }

  IMPORTANT: If the config file already exists, read it first, parse the JSON,
  add the "charles" key inside "mcpServers" (create "mcpServers" if absent),
  and write back. Do NOT overwrite other existing MCP server entries.
  If the file does not exist, create it with:
    { "mcpServers": { "charles": { ... } } }

Step 5 — Verify:
  Run: uvx charles-mcp
  Wait 3 seconds then terminate the process.
  If it starts without import errors, the installation is successful.

Step 6 — Report:
  Print: "charles-mcp installed successfully. Please restart your MCP client to load the new server."
  Also mention that Charles Proxy must be running with Web Interface enabled (Proxy → Web Interface Settings, username: admin, password: 123456).

前置条件

Python 3.10+
本机已启动 Charles Proxy
Charles Web Interface 已启用
Charles 代理默认监听 127.0.0.1:8888

推荐默认保持 CHARLES_MANAGE_LIFECYCLE=false。除非你明确希望 MCP server 接管 Charles 生命周期，否则不要让它在退出时关闭你的 Charles 进程。

环境变量

| 变量 | 默认值 | 说明 | | --- | --- | --- | | CHARLES_USER | admin | Charles Web Interface 用户名 | | CHARLES_PASS | 123456 | Charles Web Interface 密码 | | 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 server 管理 Charles 启停 | | CHARLES_REVERSE_STATE_DIR | ${CHARLES_STATE_DIR}/reverse | reverse-analysis 的 SQLite 与工件状态目录 | | CHARLES_VNEXT_STATE_DIR | 旧变量 | 旧版 reverse-analysis 状态目录。主 charles-mcp 首次启动时会自动迁移到 CHARLES_REVERSE_STATE_DIR |

当前版本重点变化（v3.0.3）

默认公开工具面已收紧为 canonical 31 个工具；legacy aliases（filter_func、proxy_by_time、list_sessions）不再默认暴露。
新增显式兼容开关：create_server(expose_legacy_tools=True) 或环境变量 CHARLES_EXPOSE_LEGACY_TOOLS=true 可启用 legacy 兼容层。
文档入口收口到 docs/README.md，并新增 docs/migrations/legacy-tools.md 作为 legacy 迁移权威说明。
新增 Agent 执行规范文档：仓库根目录增加 AGENTS.md，并新增 docs/agent-workflows.md 作为任务化调用手册。
README 与 docs/contracts/tools.md 增加 Agent 文档入口，统一使用仓库相对路径，便于跨环境查看。
高频入口工具描述已补齐最小必要语义（identity 保留、summary-first、peek/read 差异），并新增契约测试避免文档与工具描述漂移。
功能方向开始向逆向工程发展：引入 reverse-analysis 工具面，覆盖导入、解码、回放、签名候选发现与 live 逆向分析工作流。
read_live_capture 与 peek_live_capture 现在只返回路由级摘要字段，例如 host、method、path、status，不再直接抛出完整原始 Charles entry，避免在实时轮询时快速打满上下文。
query_live_capture_entries 改为只读分析入口，不会推进 live cursor。你可以基于同一个 capture_id 反复换过滤条件查询，而不会把历史增量“消费掉”。
analyze_recorded_traffic 和 query_live_capture_entries 的 summary 项会显式返回 matched_fields 与 match_reasons，便于 agent 解释“为什么这条流量被选中”。
get_traffic_entry_detail 默认 include_full_body=false、max_body_chars=2048。如果 detail 估算输出超过约 12,000 字符，会在 warnings 中提示缩小范围或关闭 full body。
detail / summary 输出会自动剥离 null 值，并隐藏 header_map、parsed_json、parsed_form、lower_name 等内部字段；需要查看头信息时请使用 headers 列表。

工具总览

README 只覆盖推荐使用的主流程工具。兼容保留入口不在本文档中展开。

Live capture tools

| 工具 | 作用 | 何时使用 | | --- | --- | --- | | start_live_capture | 启动或接管当前 live capture，并返回 capture_id | 开始实时观察前 | | read_live_capture | 按 cursor 增量读取 live capture，并只返回紧凑路由摘要 | 连续消费新增流量、只想先看 host/path/status 时 | | peek_live_capture | 预览新增流量但不推进 cursor，并只返回紧凑路由摘要 | 想先看一眼而不改变读取进度时 | | stop_live_capture | 结束 capture，并在需要时持久化快照 | 收尾或导出本次实时抓包时 | | query_live_capture_entries | 对 live capture 输出结构化 summary，且不推进 cursor | 想从实时流量里反复筛关键请求时 |

Analysis tools

| 工具 | 作用 | 何时使用 | | --- | --- | --- | | group_capture_analysis | 对 live 或 history 结果聚合分组 | 先看热点 host、path、status 时 | | get_capture_analysis_stats | 返回分类统计结果 | 想快速知道 API、静态资源、错误流量占比时 | | get_traffic_entry_detail | 读取单条 entry 的 detail，并在响应过大时给出 warnings | 已经拿到目标 entry_id，准备 drill-down 时 | | analyze_recorded_traffic | 对指定录包或最新录包输出结构化 summary，并附带匹配原因 | 想分析历史 .chlsj 时 |

History tools

| 工具 | 作用 | 何时使用 | | --- | --- | --- | | list_recordings | 列出当前已保存的录包文件 | 想先知道有哪些历史录包时 | | get_recording_snapshot | 读取某个录包的原始快照 | 需要完整查看某个保存快照时 | | query_recorded_traffic | 直接对最新录包做轻量过滤 | 需要快速查找 host、method、regex 命中时 |

Status and control tools

| 工具 | 作用 | 何时使用 | | --- | --- | --- | | charles_status | 查看 Charles 连接状态与当前 live capture 状态 | 怀疑连接异常或想确认 capture 是否仍在活动时 | | throttling | 设置 Charles 弱网预设 | 需要模拟 3G / 4G / 5G / off 等网络条件时 | | reset_environment | 恢复 Charles 配置并清理当前环境 | 需要回到干净环境时 |

Reverse analysis tools

| 工具 | 作用 | 何时使用 | | --- | --- | --- | | reverse_import_session | 将官方 Charles XML / native session 导入 canonical reverse store | 想从已导出的 Charles 会话开始回放、解码或签名分析时 | | reverse_list_captures | 列出已导入的 reverse-analysis capture | 想选择已落库的 reverse 数据集时 | | reverse_query_entries | 通过路由字段过滤已导入的 reverse entry | 想先缩小候选请求范围再看 detail / replay 时 | | reverse_get_entry_detail | 返回单条已导入 reverse entry 的 canonical detail | 想深挖某一条基线请求时 | | reverse_decode_entry_body | 解码已存储的 request / response body，支持 descriptor 驱动的 protobuf | 想拿到结构化 payload 视图时 | | reverse_replay_entry | 对单条已导入请求做 replay，可附带变异参数 | 想验证请求可重放性或参数敏感性时 | | reverse_discover_signature_candidates | 对多条已导入请求做对比并给出疑似签名字段排名 | 想定位动态 auth / sign 参数时 | | reverse_list_findings | 查看已持久化的 replay / signature finding | 想回看已有逆向证据时 | | reverse_charles_recording_status | 返回 Charles 当前录制状态和 reverse live session 状态 | 想确认 reverse live 分析是否已就绪时 | | reverse_start_live_analysis | 启动 reverse live session，并通过官方导出页面抓取当前 Charles

Charles-mcp

Related Skills