MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

C
Charles MCP
by @heizaheiza
GitHub Repo(21 stars)

Charles Proxy MCP server with live capture and structured traffic analysis

Created 3/6/2026
Updated about 6 hours ago
README
View Source
Repository documentation and setup instructions

Charles MCP Server

English README | Tool Contract

Charles MCP Server 用于把 Charles Proxy 接入 MCP 客户端，重点解决三个问题：

  • 在 Charles 正在录制时，agent 能持续读取当前 session 的实时增量数据
  • 对 live 与 history 两条链路做统一的结构化分析，而不是让 agent 直接消费原始抓包字典
  • 默认以低 token、可解释、已脱敏的方式返回结果，适合 Claude CLI、Codex CLI、Antigravity 等 MCP 客户端稳定调用

工具亮点

1. 真正可用的实时抓包链路

传统做法常见的问题是：录制过程中只能读历史 .chlsj，或者必须等录制结束再导出。本项目把实时读取和历史查询拆开，避免语义混淆。

实时工具：

  • start_live_capture：启动或接管当前 live capture
  • read_live_capture：按 cursor 读取当前 capture 的增量数据
  • peek_live_capture：不推进 cursor，只预览当前新增数据
  • stop_live_capture：更稳地收尾，内置一次短重试

这意味着 agent 可以边录边看边分析，而不是只能做离线回放。

2. 面向 agent 的低 token 分析输出

项目默认不是把完整 request/response body 一股脑返回给 agent，而是采用 summary-first 模式。

分析工具：

  • query_live_capture_entries
  • analyze_recorded_traffic
  • group_capture_analysis
  • get_capture_analysis_stats
  • get_traffic_entry_detail

默认策略：

  • preset="api_focus"
  • 优先保留 JSON / API / GraphQL / Auth / 错误请求
  • 默认过滤 static_asset、media、font、connect_tunnel 等高噪音流量
  • 默认限制 max_items、max_preview_chars、max_headers_per_side
  • summary 结果带 filtered_out_count 和 filtered_out_by_class，便于 agent 理解被过滤了什么

3. 结构化 drill-down，而不是原始字典拼接

当 agent 需要深挖某条请求时，再调用 get_traffic_entry_detail。这样可以避免默认返回超大 payload，同时保留深入分析能力。

detail 设计原则：

  • 默认仍然脱敏
  • 默认不返回 full body
  • 只有显式请求时才返回更完整的 request/response 内容
  • 适合和 group_capture_analysis -> query_live_capture_entries -> get_traffic_entry_detail 组合使用

4. 更稳的 stop 收尾语义

stop_live_capture 不再是“失败就直接把状态打死”的工具。

当前 stop 语义：

  • 内部会做一次短重试
  • 如果重试后成功，返回 status="stopped"
  • 如果两次 stop 都失败，返回 status="stop_failed"
  • 同时返回：
    • recoverable=true
    • active_capture_preserved=true

这表示 active capture 仍保留，agent 可以继续读取、诊断，再次调用 stop，而不是直接丢掉上下文。

前置条件

1. Python 与 Charles

  • Python 3.10+
  • 本机已启动 Charles Proxy
  • Charles Web Interface 已启用
  • Charles 代理默认监听 127.0.0.1:8888

2. 在 Charles 中开启 Web Interface

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

请确认：

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

菜单位置示意：

Charles Web Interface Menu

设置窗口示意：

Charles Web Interface Settings

安装

pip install -e .[dev]

安装后的命令入口：

charles-mcp

包入口：

charles_mcp.main:main

仓库内兼容入口：

python charles-mcp-server.py

环境变量

| 变量 | 默认值 | 说明 | | --- | --- | --- | | 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 启停 |

推荐默认值是 CHARLES_MANAGE_LIFECYCLE=false。除非你明确希望 MCP server 接管 Charles 生命周期，否则不要让它在退出时关闭你自己的 Charles 进程。

各种终端中的配置方法

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()"

MCP 客户端配置示例

通用 stdio MCP 配置

适用于支持 command + args + env 的 MCP 客户端。

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

Claude CLI

使用 claude mcp add-json 添加 stdio MCP server：

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

仓库本地开发配置：

claude mcp add-json charles '{
  "type": "stdio",
  "command": "python",
  "args": ["~/Charles-mcp/charles-mcp-server.py"],
  "env": {
    "CHARLES_USER": "admin",
    "CHARLES_PASS": "123456",
    "CHARLES_MANAGE_LIFECYCLE": "false"
  }
}'

检查当前配置：

claude mcp get charles

Codex CLI

Codex CLI 从 ~/.codex/config.toml 读取 MCP server 配置。推荐写法：

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

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

仓库本地开发写法：

[mcp_servers.charles]
command = "python"
args = ["~/Charles-mcp/charles-mcp-server.py"]

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

Antigravity

Antigravity 支持在 Manage MCP Servers 或 View raw config 中直接编辑 mcpServers JSON：

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

仓库本地开发写法：

{
  "mcpServers": {
    "charles": {
      "command": "python",
      "args": ["~/Charles-mcp/charles-mcp-server.py"],
      "cwd": "~/Charles-mcp",
      "env": {
        "CHARLES_USER": "admin",
        "CHARLES_PASS": "123456",
        "CHARLES_MANAGE_LIFECYCLE": "false"
      }
    }
  }
}

推荐调用路径

实时分析路径

推荐给 agent 的调用顺序：

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

原因：

  • group_capture_analysis 最省 token，适合先看热点 host/path/status
  • query_live_capture_entries 返回结构化 summary，适合持续筛选关键请求
  • get_traffic_entry_detail 只在确认目标条目后再展开完整细节

历史分析路径

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

Agent 对 stop_failed + recoverable=true 的处理规范

stop_live_capture 有两个稳定结束态：

  1. status="stopped"
  • stop 成功
  • active capture 已关闭
  • 当 persist=true 时可能返回 persisted_path
  1. status="stop_failed"
  • 一次短重试后仍失败
  • 这不代表 live capture 已关闭
  • 需要和以下字段一起解释：
    • recoverable=true
    • active_capture_preserved=true

当工具返回：

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

agent 应该：

  1. 保留 capture_id
  2. 不要假设 Charles 已经停止录制
  3. 检查 error 和 warnings
  4. 如有必要，调用 charles_status 确认当前状态
  5. 如果还要继续观察流量，继续调用 read_live_capture
  6. 如果要继续收尾，再次调用 stop_live_capture
  7. 只有 status="stopped" 才表示真正关闭完成

相关 warning：

  • stop_recording_retry_succeeded
  • stop_recording_failed_after_retry

summary-first 契约

默认契约是：不要一上来就拉大体积 detail。先看 group 或 summary，再决定是否 drill-down。

query_live_capture_entries

适用：

  • 对当前 live capture 做结构化分析

返回重点：

  • items
  • matched_count
  • filtered_out_count
  • filtered_out_by_class
  • next_cursor
  • warnings

analyze_recorded_traffic

适用：

  • 对历史 .chlsj 记录做结构化分析

返回重点：

  • items
  • matched_count
  • filtered_out_count
  • filtered_out_by_class
  • warnings

group_capture_analysis

适用：

  • 在查看单条 summary 之前，先用最低 token 成本识别热点

支持分组字段：

  • host
  • path
  • response_status
  • resource_class
  • method
  • host_path
  • host_status

返回重点：

  • groups
  • matched_count
  • filtered_out_count
  • filtered_out_by_class
  • warnings

token 优化约束

分析类工具默认会过滤高噪音流量。默认契约的目标是让 agent 更稳定，而不是返回全量原始 dump。

默认过滤或降权：

  • control.charles
  • CONNECT
  • static_asset
  • media
  • font
  • 其他低价值高噪音请求

推荐默认：

  • 保持 preset="api_focus"
  • 控制较小的 max_items
  • 没有明确必要时，不要请求 include_full_body=true
  • 先使用 group_capture_analysis
  • 再使用 query_live_capture_entries

如果结果被裁剪，agent 应结合这些字段理解当前输出：

  • truncated
  • filtered_out_count
  • filtered_out_by_class

detail drill-down 契约

get_traffic_entry_detail

推荐用途：

  • 对单条 entry 做精细分析
  • 不作为批量分析的第一步

推荐规则：

  1. 先通过 summary 或 group 确定 entry_id
  2. 再调用 get_traffic_entry_detail
  3. 没有明确必要时，不要默认 include_full_body=true
  4. 没有明确必要时，不要默认 include_sensitive=true

主要工具

Live tools

  • start_live_capture
  • read_live_capture
  • peek_live_capture
  • stop_live_capture
  • query_live_capture_entries
  • get_capture_analysis_stats
  • group_capture_analysis

History tools

  • analyze_recorded_traffic
  • query_recorded_traffic
  • list_recordings
  • get_recording_snapshot
  • get_traffic_entry_detail

Status / control tools

  • charles_status
  • throttling
  • reset_environment

安全默认值

敏感字段默认会被脱敏，包括但不限于：

  • Authorization
  • Proxy-Authorization
  • Cookie
  • Set-Cookie
  • X-Api-Key
  • token
  • access_token
  • refresh_token
  • session
  • password
  • secret

summary 输出应始终视为脱敏视图。

已废弃但保留兼容的工具

以下工具仍然存在，但不应继续作为新的主流程入口：

  • proxy_by_time
  • filter_func

开发

运行测试：

python -m pytest -q

常用本地检查：

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

感谢支持

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

微信赞赏码

微信赞赏码

USDT-TRC20

TCudxn9ByCxPZHXLtvqBjFmLWXywBoicRs

感谢你的支持与认可。

另见：

Quick Setup
Installation guide for this server

Install Package (if required)

uvx charles-mcp

Cursor configuration (mcp.json)

{ "mcpServers": { "heizaheiza-charles-mcp": { "command": "uvx", "args": [ "charles-mcp" ] } } }