Skip to main content
Glama

Charles MCP Server

专为 AI agent 逆向分析设计的 Charles Proxy MCP 服务器。

设计原则:MCP 只做数据通道,不替 agent 做分析判断。工具职责是取数据、过滤、呈现,推理交给 agent。

核心机制

Checkpoint 时间线

每次调用 harvest_data() 都会:

  1. 从 Charles 导出当前 session

  2. 取上次收割后产生的新条目(按 times.start 毫秒时间戳增量判断)

  3. 将新条目写入内存 ARCHIVE

  4. 在时间线上记录一个 checkpoint

  5. 清空 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

工具总览

收割

工具

说明

harvest_data(fresh_start=False)

增量收割,创建 checkpoint。fresh_start=True 插入重置点,之后只看新流量

时间线

工具

说明

list_checkpoints()

查看所有 checkpoint,了解收割时间线

load_checkpoint(id)

切换到指定 checkpoint 的数据窗口

概览

工具

说明

summarize_traffic()

统计当前窗口的 host / path / 状态码 / 方法分布,不拉取 body

过滤(均返回精简视图,含 body 预览)

工具

说明

filter_by_host(keyword)

按域名过滤,只匹配顶层 host 字段

filter_by_path(keyword)

按 URL 路径关键词过滤

filter_by_method(method)

按 HTTP 方法过滤(GET / POST 等)

filter_by_status(code)

按 HTTP 状态码过滤

check_keyword_exists(keyword)

探测关键词位置,返回轻量索引,并解锁 filter_by_keyword

filter_by_keyword(keyword)

返回含关键词的条目预览,匹配数 > 30 时需先调 check

filter_by_encryption(threshold=3.9)

按香农熵扫描,找出疑似加密/压缩/编码的 body,按熵值降序

详情

工具

说明

get_raw_data(entry_id)

获取完整原始数据。先在当前窗口找,找不到从 ARCHIVE 全局搜

环境控制

工具

说明

set_throttling(preset)

开启 / 关闭弱网模拟,MCP 退出时自动还原

get_proxy_status()

返回当前连接模式(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.json

  • Windows:%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_USER

Charles-mcp-server

Charles Web Interface 用户名

CHARLES_PASS

123456

Charles Web Interface 密码

CHARLES_PROXY_HOST

127.0.0.1

Charles 代理地址

CHARLES_PROXY_PORT

8888

Charles 代理端口

CHARLES_MCP_MODE

external

managed-headless 时自动启动并托管 Charles Headless

CHARLES_EXECUTABLE

自动检测

Charles 可执行文件路径(managed-headless 模式使用)

CHARLES_MCP_RUNTIME_DIR

~/.charles-mcp-server

Headless 模式的配置、数据与日志目录


License

MIT License — Owner: tianhetonghua

Available Tools

13 tools
check_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

    A4.2/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Integrates 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.
      18
      112 PyPI
      333
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      4
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      47
      MIT