Charles MCP Server
Provides tools for harvesting, filtering, and analyzing network traffic from Charles Proxy, enabling AI agents to perform reverse engineering and debugging of web requests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Charles MCP Server Harvest current traffic and show summary."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Charles MCP Server
专为 AI agent 逆向分析设计的 Charles Proxy MCP 服务器。
设计原则:MCP 只做数据通道,不替 agent 做分析判断。工具职责是取数据、过滤、呈现,推理交给 agent。
核心机制
Checkpoint 时间线
每次调用 harvest_data() 都会:
从 Charles 导出当前 session
取上次收割后产生的新条目(按
times.start毫秒时间戳增量判断)将新条目写入内存 ARCHIVE
在时间线上记录一个 checkpoint
清空 Charles session,重启录制(保持导出始终轻量)
agent 可通过 load_checkpoint(n) 随时回到任意历史时间窗口,所有过滤工具自动在那个范围内工作。
资源文件占位符
图片、JS、CSS、二进制等资源的 body 不传给 agent,替换为 [image/png 45.2KB] 形式的占位符。agent 知道类型和大小,按需调 get_raw_data 获取实际内容。
关键词互锁
filter_by_keyword 在匹配数 > 30 时要求先调 check_keyword_exists,避免一次性拉取大量 body 撑爆上下文。
Related MCP server: mitmproxy-mcp
工具总览
收割
工具 | 说明 |
| 增量收割,创建 checkpoint。 |
时间线
工具 | 说明 |
| 查看所有 checkpoint,了解收割时间线 |
| 切换到指定 checkpoint 的数据窗口 |
概览
工具 | 说明 |
| 统计当前窗口的 host / path / 状态码 / 方法分布,不拉取 body |
过滤(均返回精简视图,含 body 预览)
工具 | 说明 |
| 按域名过滤,只匹配顶层 host 字段 |
| 按 URL 路径关键词过滤 |
| 按 HTTP 方法过滤(GET / POST 等) |
| 按 HTTP 状态码过滤 |
| 探测关键词位置,返回轻量索引,并解锁 filter_by_keyword |
| 返回含关键词的条目预览,匹配数 > 30 时需先调 check |
| 按香农熵扫描,找出疑似加密/压缩/编码的 body,按熵值降序 |
详情
工具 | 说明 |
| 获取完整原始数据。先在当前窗口找,找不到从 ARCHIVE 全局搜 |
环境控制
工具 | 说明 |
| 开启 / 关闭弱网模拟,MCP 退出时自动还原 |
| 返回当前连接模式(external / managed-headless)与代理运行状态 |
典型工作流
harvest_data() # 同步流量,创建 checkpoint
summarize_traffic() # 看全局:哪个 host 流量多,有没有大量 403
filter_by_host("api.xxx") # 缩小到目标域名
filter_by_encryption() # 找加密字段
get_raw_data(entry_id) # 取完整报文深度分析切换分析目标:
harvest_data(fresh_start=True) # 标记重置点,不加载旧流量
# 在 App 触发目标操作
harvest_data() # 只拿新流量回溯历史:
list_checkpoints() # 查看时间线
load_checkpoint(2) # 切到第 2 次收割的数据
filter_by_keyword("sign") # 在那个时间窗口里搜前置条件
模式一:External(默认)
Charles Proxy 已启动,开启 Web Interface:Proxy → Web Interface Settings
勾选 Enable web interface
用户名:
Charles-mcp-server(或通过环境变量自定义)密码:
123456(或通过环境变量自定义)
模式二:Managed Headless(自动托管)
设置 CHARLES_MCP_MODE=managed-headless 后,MCP 启动时自动拉起一个隔离的 Charles --headless 进程,自动生成随机 Web Interface 凭据,无需手动配置。MCP 退出时自动终止 Charles 进程并释放端口。文件锁保证同一时刻只有一个 MCP 实例托管 Charles。
安装
方式一:PyPI(推荐)
pip install charles-mcp-server方式二:从源码安装
git clone <repo-url>
cd Charles-mcp-server
pip install .方式三:让 AI 自动安装
将下方提示词完整粘贴给任意 AI agent(Claude Code、Cursor Agent、Codex 等),agent 会自动完成安装和配置:
请帮我安装并配置 "charles-mcp-server" MCP server,按以下步骤执行:
Step 1 — 检测操作系统:
判断当前系统是 Windows、macOS 还是 Linux。
Step 2 — 安装 charles-mcp-server:
运行:pip install charles-mcp-server
如果失败,尝试:pip3 install charles-mcp-server
安装完成后验证:charles-mcp-server --help(有输出即成功)
Step 3 — 检测 MCP 客户端(按顺序匹配,用第一个命中的):
a) Claude Code — 运行:claude --version
成功则执行以下命令,然后跳到 Step 5:
claude mcp add-json charles '{"type":"stdio","command":"charles-mcp-server","args":[]}'
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
e) Codex CLI — 检查:~/.codex/config.toml
f) Gemini CLI — 检查:~/.gemini/settings.json
如果以上均未找到,询问用户使用的是哪个客户端。
Step 4 — 写入配置(适用于 b/c/d/f 的 JSON 格式客户端):
要添加的配置项为:
"charles": {
"command": "charles-mcp-server",
"args": []
}
重要:如果配置文件已存在,先读取再解析 JSON,
在 "mcpServers" 内追加 "charles" 键(若无 "mcpServers" 则创建),
不要覆盖已有的其他 MCP server 配置。
如果文件不存在,创建并写入:
{ "mcpServers": { "charles": { "command": "charles-mcp-server", "args": [] } } }
适用于 e(Codex CLI TOML 格式):
在 ~/.codex/config.toml 中追加:
[mcp_servers.charles]
command = "charles-mcp-server"
args = []
Step 5 — 验证:
运行:charles-mcp-server
等待 2 秒后终止进程。
没有 import 报错则安装成功。
Step 6 — 报告结果:
输出:"charles-mcp-server 安装完成,请重启 MCP 客户端以加载新服务。"
并提示:Charles Proxy 需处于运行状态,且已在 Proxy → Web Interface Settings 中
启用 Web Interface(用户名:Charles-mcp-server,密码:123456)。各客户端配置
所有客户端使用相同的 MCP server,只是配置文件路径和格式不同。
Claude Code(CC)
claude mcp add-json charles '{
"type": "stdio",
"command": "charles-mcp-server",
"args": []
}'如需自定义 Charles 账号:
claude mcp add-json charles '{
"type": "stdio",
"command": "charles-mcp-server",
"args": [],
"env": {
"CHARLES_USER": "your-username",
"CHARLES_PASS": "your-password"
}
}'Claude Desktop
配置文件路径:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"charles": {
"command": "charles-mcp-server",
"args": []
}
}
}Cursor
配置文件路径(二选一):
全局:
~/.cursor/mcp.json项目级:
.cursor/mcp.json(只对当前项目生效)
{
"mcpServers": {
"charles": {
"command": "charles-mcp-server",
"args": []
}
}
}Windsurf
配置文件路径:~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"charles": {
"command": "charles-mcp-server",
"args": []
}
}
}Codex CLI
配置文件路径:~/.codex/config.toml
[mcp_servers.charles]
command = "charles-mcp-server"
args = []自定义账号:
[mcp_servers.charles]
command = "charles-mcp-server"
args = []
[mcp_servers.charles.env]
CHARLES_USER = "your-username"
CHARLES_PASS = "your-password"Gemini CLI
配置文件路径:~/.gemini/settings.json
{
"mcpServers": {
"charles": {
"command": "charles-mcp-server",
"args": []
}
}
}pyenv 环境(通用)
如果通过 pyenv 管理 Python 环境,将上述所有配置的 "command" 替换为对应 Python 的绝对路径,并改用 -m 方式启动:
{
"mcpServers": {
"charles": {
"command": "/path/to/pyenv/versions/3.11.x/bin/python",
"args": ["-m", "charles_mcp_server.main"]
}
}
}环境变量
所有客户端均支持通过环境变量覆盖默认配置:
变量 | 默认值 | 说明 |
|
| Charles Web Interface 用户名 |
|
| Charles Web Interface 密码 |
|
| Charles 代理地址 |
|
| Charles 代理端口 |
|
|
|
| 自动检测 | Charles 可执行文件路径(managed-headless 模式使用) |
|
| Headless 模式的配置、数据与日志目录 |
License
MIT License — Owner: tianhetonghua
Available Tools
13 toolscheck_keyword_existsA
【互锁-1】探测关键词在当前 checkpoint 的哪些条目中出现。
只返回 id + 命中位置的轻量索引,不返回 body 内容。 调用后 filter_by_keyword 对该关键词的批量限制解除(5 分钟内有效)。
Inputs: keyword (required). Returns: result
filter_by_encryptionA
扫描当前 checkpoint 的所有条目,找出 body 疑似加密/压缩/编码的请求。
按 max(req_entropy, res_entropy) 降序排列。
threshold 默认 3.9:纯文本 JSON 通常 2.53.5,Base64 约 4.05.0,加密 > 5.0。
limit 默认 20,上限 100。
Inputs: threshold, limit. Returns: result
filter_by_hostA
按 host 字段过滤,返回精简视图。
只匹配 entry 顶层的 host 字段,不会误命中 body 或 headers 中出现的域名。 支持部分匹配,例如 'example.com' 可匹配所有子域名。 limit 默认 15,上限 50,返回最近 N 条。
Inputs: host_keyword (required), limit. Returns: result
filter_by_keywordA
【互锁-2】返回含关键词的条目精简视图(含 body 预览)。
匹配数 > 30 时须先调用 check_keyword_exists 解锁,防止上下文溢出。 limit 默认 10,上限 50,返回最近 N 条。
Inputs: keyword (required), limit. Returns: result
filter_by_methodA
按 HTTP 方法过滤(GET / POST / PUT / DELETE 等),返回精简视图。
大小写不敏感。limit 默认 15,上限 50,返回最近 N 条。
Inputs: method (required), limit. Returns: result
filter_by_pathA
按 URL 路径关键词过滤,返回精简视图。
适合快速定位某个业务接口,例如 '/api/sign'、'/login'。 limit 默认 15,上限 50,返回最近 N 条。
Inputs: path_keyword (required), limit. Returns: result
filter_by_statusA
按 HTTP 状态码过滤,返回精简视图。
适合排查异常请求,例如 403(鉴权失败)、500(服务错误)。 limit 默认 15,上限 50,返回最近 N 条。
Inputs: status_code (required), limit. Returns: result
get_raw_dataA
获取指定条目的完整原始数据(headers、body、timing 等全部字段)。
优先在当前 checkpoint 查找,找不到时从 ARCHIVE 全局搜索。 这样即使切换了 checkpoint,仍可用 entry_id 直接取历史数据。
Inputs: entry_id (required). Returns: result
harvest_dataA
从 Charles 同步增量流量,并在时间线上创建一个新 checkpoint。
【fresh_start=False】(默认) 取上次 harvest 之后产生的新条目,写入 ARCHIVE,创建 checkpoint。 首次调用时加载 session 全部流量。
【fresh_start=True】 在时间线上插一个"重置点",不加载任何条目。 之后的 harvest_data() 只返回此刻之后的新流量。 典型用法:切换分析目标前调用一次。
每次调用都会:
将新条目存入 ARCHIVE(可通过 load_checkpoint 随时回溯)
将 CACHE 切换到本次新增的条目
清空 Charles session 并重启录制(导出始终只含最新增量)
使所有关键词授权失效
Inputs: fresh_start. Returns: result
list_checkpointsA
列出所有 checkpoint,展示完整的收割时间线。
每条记录包含: id checkpoint 序号 read_at 收割时间(HH:MM:SS) count 本次新增条目数 start_time 本批流量的最早请求时间 end_time 本批流量的最晚请求时间 is_reset 是否为 fresh_start 重置点
当前正在查看的 checkpoint 由 current_checkpoint_id 标注。
Inputs: no named parameters. Returns: result
load_checkpointA
将 CACHE 切换到指定 checkpoint 的数据,所有过滤工具随即在该时间窗口内工作。
这是只读回溯——ARCHIVE 和 CHECKPOINTS 不会被修改。 调用 harvest_data() 可随时切回最新增量。
checkpoint_id:来自 list_checkpoints 返回的 id 字段。
Inputs: checkpoint_id (required). Returns: result
set_throttlingA
切换网络带宽限制。
preset 为预设名称 → 开启弱网;preset 为 null → 关闭弱网模拟。
MCP 进程退出时自动关闭弱网,无需手动清理。
可用预设(直接填名称字符串): 56 kbps Modem | 256 kbps ISDN/DSL | 512 kbps ISDN/DSL 2 Mbps ADSL | 8 Mbps ADSL2 | 16 Mbps ADSL2+ 32 Mbps VDSL | 32 Mbps Fibre | 100 Mbps Fibre 3G | 4G
Inputs: preset (required). Returns: result
summarize_trafficA
对当前 checkpoint 的流量做全局统计,帮助 agent 快速定向。
不拉取任何 body,只统计路由维度: top_hosts 流量最多的域名 top_paths 最活跃的路径前缀(取前两段) status_dist HTTP 状态码分布 method_dist HTTP 方法分布
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct aspect of traffic capture/analysis: filter tools focus on different fields, checkpoint tools manage timelines, and utilities cover data retrieval, throttling, and summarization. The only pair (check_keyword_exists and filter_by_keyword) is clearly linked as a required sequence, avoiding ambiguity.
All tools use snake_case. Filter tools consistently start with 'filter_by_', while others use verb_noun patterns (e.g., harvest_data, get_raw_data). This provides predictability, though not all follow the exact same template.
13 tools cover the full lifecycle of traffic interception (harvest, checkpoint management, multiple filters, raw data retrieval, network throttling, and traffic summarization) without redundancy or unnecessary scope.
The tool surface enables full CRUD-like operations on captured traffic: harvest (create checkpoint), list/load checkpoints (read), filter by multiple criteria, get raw data, and analyze summaries. Throttling is also included, covering common debugging needs.
Maintenance
Related MCP Connectors
Proxy-rotated web scraping and cross-platform intelligence for AI agents.
Capture, inspect, send and assert on webhooks and inbound email from your coding agent.
Debug webhooks from your AI agent: inspect and replay captured webhooks on localhost.
Browse the agentic web with Darwin: search, communicate, authenticate, and act through agents.
Related MCP Servers
- AlicenseBqualityCmaintenanceIntegrates Charles Proxy with MCP clients to provide real-time and historical network traffic capture and structured analysis. It features a summary-first approach that filters noise and desensitizes data for efficient, low-token agent debugging and monitoring.18112 PyPI333MIT
- AlicenseCqualityBmaintenanceTransforms mitmproxy into a toolset for AI agents to inspect, modify, and replay HTTP/HTTPS traffic in real-time.25136MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI to analyze real-time HTTP(S) traffic captured by ProxyPin, with tools to browse, search, and inspect requests and responses, as well as access saved history sessions.11 npm4MIT
- AlicenseBqualityBmaintenanceEnables AI agents to connect to Charles Proxy for live and historical traffic analysis, summary-first insights, request detail inspection, and data-driven mock creation via Map Local/Remote.47MIT