CharlesCAUTION
Charles Proxy MCP server for AI agents with live capture, structured traffic analysis, and agent-friendly tool contracts
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://pypi.org/project/charles-mcp/) [](LICENSE) [](https://pypi.org/project/charles-mcp/)
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
菜单位置示意:
设置窗口示意:
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",
"CH565bf4d0035aOBSERVED · 2026-10-05Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add charles-mcp --env CHARLES_PASS=${CHARLES_PASS} -- uvx charles-mcp{
"mcpServers": {
"charles-mcp": {
"command": "uvx",
"args": [
"charles-mcp"
],
"env": {
"CHARLES_PASS": "${CHARLES_PASS}"
}
}
}
}Exposed tools (34)
24 read · 9 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
analyze_recorded_traffic | read | Analyze a saved recording snapshot with compact summaries. |
charles_status | read | Check Charles connectivity and active live-capture state. |
filter_func | read | Deprecated compatibility alias. Prefer canonical live/history/reverse tools. |
get_capture_analysis_stats | read | Return coarse traffic class counts for a live capture or saved recording. |
get_recording_snapshot | read | Load a saved recording snapshot. This tool never reads the live Charles session. |
get_traffic_entry_detail | read | Load one traffic entry detail view for drill-down inspection. |
group_capture_analysis | read | Group analyzed traffic so the agent can inspect hot spots with lower token cost. |
list_recordings | read | List saved recording files using an explicit history-oriented tool name. |
list_sessions | read | Deprecated compatibility alias. Prefer canonical live/history/reverse tools. |
peek_live_capture | read | Preview incremental traffic without advancing the cursor. |
proxy_by_time | read | Deprecated compatibility alias. Prefer canonical live/history/reverse tools. |
query_live_capture_entries | read | Analyze the active live capture with structured summary-first filtering. |
query_recorded_traffic | read | Query the latest saved recording. This tool never reads the live Charles session. |
read_live_capture | read | Read incremental traffic and advance the cursor. |
reset_environment | destructive | Reset the Charles environment and restore the saved configuration. |
reverse_analyze_live_api_flow | write | Run a task-oriented live API reverse-analysis workflow on new traffic. |
reverse_analyze_live_login_flow | write | Run a task-oriented live login/auth reverse-analysis workflow on new traffic. |
reverse_analyze_live_signature_flow | write | Run a task-oriented live signature reverse-analysis workflow on new traffic. |
reverse_charles_recording_status | read | Inspect Charles recording state and optional reverse live-session state. |
reverse_decode_entry_body | read | Decode a stored request/response body, including protobuf when a descriptor is provided. |
reverse_discover_signature_candidates | read | Compare multiple requests and rank fields that look signature-related. |
reverse_get_entry_detail | read | Get the canonical detail view for one imported entry. |
reverse_import_session | write | Import an official Charles XML/native session into the canonical reverse-analysis store. |
reverse_list_captures | read | List imported captures from the local SQLite store. |
reverse_list_findings | read | List persisted findings from replay or signature-candidate analysis. |
reverse_peek_live_entries | read | Snapshot the current Charles session and inspect only new entries without advancing the live cursor. |
reverse_query_entries | read | Query imported entries using route-level filters. |
reverse_read_live_entries | read | Snapshot the current Charles session and advance the live cursor to consume new entries. |
reverse_replay_entry | read | Replay one imported entry with optional mutations and store the experiment result. |
reverse_start_live_analysis | write | Start a near-real-time live analysis session without using undocumented JSON export. |
reverse_stop_live_analysis | write | Stop a reverse live-analysis session and optionally restore Charles recording. |
start_live_capture | write | Start or adopt a live capture session for incremental polling. |
stop_live_capture | write | Stop an active live capture and optionally persist the filtered snapshot. |
throttling | write | Set a network throttling preset in Charles. |
Trust audit
CAUTIONgrade B · trust 80/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (3 observation(s))
- Network
- declared (5 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (19)
"""Configuration management for the Charles MCP server."""
"""Schemas for normalized HTTP traffic entries."""
"""Schemas for traffic analysis queries."""
"""History-oriented recording access for Charles MCP."""
reset_environment
return hashlib.sha1(payload.encode("utf-8")).hexdigest()return hashlib.sha1(f"{capture_id}|{sequence_no}|{side}".encode()).hexdigest()return hashlib.sha1(payload.encode("utf-8")).hexdigest()return hashlib.sha1(payload.encode("utf-8")).hexdigest()assert "../../AGENTS.md" in contract
assert config.proxy_url == "http://127.0.0.1:8888"
monkeypatch.setenv("HTTP_PROXY", "http://127.0.0.1:1")monkeypatch.setenv("HTTPS_PROXY", "http://127.0.0.1:1")payload = base64.b64decode(text, validate=False)
raw_bytes = base64.b64decode(text, validate=False)
"""Unit tests for configuration helpers."""
mcp, httpx, pydantic, jmespath, defusedxml, brotli, zstandard, protobuf
- macOS/Linux: run: curl -LsSf https://astral.sh/uv/install.sh | sh
- macOS/Linux: run: curl -LsSf https://astral.sh/uv/install.sh | sh
Gates applied: no_behavioural_pass.
565bf4d0035afull audit observations/trust-audit/mcp-server/heizaheiza__charles.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-05 | 565bf4d0035a | CAUTION | B | 80 | first audit |
Questions
What is the Charles MCP server?
Charles Proxy MCP server for AI agents with live capture, structured traffic analysis, and agent-friendly tool contracts
What tools does Charles expose?
34 in total: 24 read-only, 9 that write, and 1 that can delete or overwrite (reset_environment). Every one is listed on this page with its risk.
Is Charles safe to connect to an agent?
With care. The audit graded it B (80/100) and found 19 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Charles need?
It reads CHARLES_PASS from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Charles run?
It speaks stdio, so it runs as a local process your client starts. It is published on PyPI as charles-mcp.
How current is this page?
The grade is for one exact copy of the source (565bf4d0035a), read on 2026-10-05. The repository is watched and re-audited when it changes.