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 "Install 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 ServerHarvest 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: Charles MCP Server
工具总览
收割
工具 | 说明 |
| 增量收割,创建 checkpoint。 |
时间线
工具 | 说明 |
| 查看所有 checkpoint,了解收割时间线 |
| 切换到指定 checkpoint 的数据窗口 |
概览
工具 | 说明 |
| 统计当前窗口的 host / path / 状态码 / 方法分布,不拉取 body |
过滤(均返回精简视图,含 body 预览)
工具 | 说明 |
| 按域名过滤,只匹配顶层 host 字段 |
| 按 URL 路径关键词过滤 |
| 按 HTTP 方法过滤(GET / POST 等) |
| 按 HTTP 状态码过滤 |
| 探测关键词位置,返回轻量索引,并解锁 filter_by_keyword |
| 返回含关键词的条目预览,匹配数 > 30 时需先调 check |
| 按香农熵扫描,找出疑似加密/压缩/编码的 body,按熵值降序 |
详情
工具 | 说明 |
| 获取完整原始数据。先在当前窗口找,找不到从 ARCHIVE 全局搜 |
环境控制
工具 | 说明 |
| 开启 / 关闭弱网模拟,MCP 退出时自动还原 |
典型工作流
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") # 在那个时间窗口里搜前置条件
Charles Proxy 已启动,开启 Web Interface:Proxy → Web Interface Settings
勾选 Enable web interface
用户名:
Charles-mcp-server(或通过环境变量自定义)密码:
123456(或通过环境变量自定义)
安装
方式一: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 代理端口 |
License
MIT License — Owner: tianhetonghua
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/tianhetonghua/Charles-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server