Charles MCP Server

English README | Tool Contract

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

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

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

快速开始

1. 开启 Charles Web Interface

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

请确认：

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

菜单位置示意：

设置窗口示意：

2. 安装

pip install -e .[dev]

命令入口：

charles-mcp

包入口：

charles_mcp.main:main

仓库内兼容入口：

python charles-mcp-server.py

3. 设置环境变量并启动

PowerShell

$env:CHARLES_USER = "admin"
$env:CHARLES_PASS = "123456"
$env:CHARLES_PROXY_HOST = "127.0.0.1"
$env:CHARLES_PROXY_PORT = "8888"
$env:CHARLES_MANAGE_LIFECYCLE = "false"
charles-mcp

Windows CMD

set CHARLES_USER=admin
set CHARLES_PASS=123456
set CHARLES_PROXY_HOST=127.0.0.1
set CHARLES_PROXY_PORT=8888
set CHARLES_MANAGE_LIFECYCLE=false
charles-mcp

Git Bash / Bash / Zsh

export CHARLES_USER=admin
export CHARLES_PASS=123456
export CHARLES_PROXY_HOST=127.0.0.1
export CHARLES_PROXY_PORT=8888
export CHARLES_MANAGE_LIFECYCLE=false
charles-mcp

直接使用 Python 入口

python -c "from charles_mcp.main import main; main()"

4. 配置到 MCP 客户端

通用 stdio MCP 配置：

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

Claude CLI

claude mcp add-json charles '{
  "type": "stdio",
  "command": "charles-mcp",
  "env": {
    "CHARLES_USER": "admin",
    "CHARLES_PASS": "123456",
    "CHARLES_MANAGE_LIFECYCLE": "false"
  }
}'

Codex CLI

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

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

Antigravity

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

前置条件

• 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 启停

推荐使用路径

实时分析

1. start_live_capture
2. group_capture_analysis
3. query_live_capture_entries
4. get_traffic_entry_detail
5. stop_live_capture

这条路径的目标是先用最少 token 找到热点，再按需展开单条请求。

历史分析

1. list_recordings
2. analyze_recorded_traffic
3. group_capture_analysis(source="history")
4. get_traffic_entry_detail

这条路径适合先浏览录包，再对结构化 summary 做筛选和 drill-down。

工具总览

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

Live capture tools

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

Analysis tools

工具	作用	何时使用
group_capture_analysis	对 live 或 history 结果聚合分组	先看热点 host、path、status 时
get_capture_analysis_stats	返回分类统计结果	想快速知道 API、静态资源、错误流量占比时
get_traffic_entry_detail	读取单条 entry 的 detail	已经拿到目标 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 配置并清理当前环境	需要回到干净环境时

关键使用约定

1. 默认返回原始数据

当前版本不再做 header/body 脱敏：

• summary / detail / live / history 默认都返回原始内容
• include_sensitive 参数仅保留兼容，不再影响返回结果

2. 先 summary，再 detail

推荐先用 group_capture_analysis、query_live_capture_entries 或 analyze_recorded_traffic 确认目标，再调用 get_traffic_entry_detail。

默认不要一开始就请求 include_full_body=true。

3. history detail 需要稳定 source identity

history summary 会返回 recording_path，live summary 会返回 capture_id。

对 get_traffic_entry_detail：

• history 场景优先传 recording_path
• live 场景优先传 capture_id

4. stop_live_capture 的失败是可恢复的

stop_live_capture 有两个稳定结束态：

• status="stopped"：真正关闭完成
• status="stop_failed"：短重试后仍失败，但 capture 仍保留

当返回 stop_failed 时，应同时关注：

• recoverable
• active_capture_preserved

如果结果是：

{
  "status": "stop_failed",
  "recoverable": true,
  "active_capture_preserved": true
}

说明当前 capture 仍然可继续读取、诊断、再次 stop，而不是已经被关闭。

开发

运行测试：

python -m pytest -q

常用本地检查：

python charles-mcp-server.py
python -c "from charles_mcp.main import main; main()"

感谢支持

如果这个项目对你有帮助，欢迎请我喝杯咖啡，支持后续维护与迭代。

微信赞赏码

USDT-TRC20

TCudxn9ByCxPZHXLtvqBjFmLWXywBoicRs

另见

• English README
• Tool Contract