charles-mcp: an MCP server that lets an AI agent read Charles Proxy traffic

The gap charles-mcp fills between Charles Proxy and an agent

Charles Proxy is a desktop interception proxy. It records HTTP and HTTPS traffic through a GUI, and the people who use it spend a lot of time scrolling a session list, filtering by host, and opening individual requests to read headers and bodies. An AI agent cannot do that. It cannot see the window, and if you paste a raw capture export into a prompt you burn context on fields nobody asked about.

charles-mcp is an MCP server that sits between the two. According to the README, it solves three problems specifically: an agent can keep reading incremental traffic while a recording is still in progress, live and history analysis both go through the same structured layer instead of raw capture dictionaries, and output is summary-first by default so the agent looks at hotspots and summaries before drilling down to a single entry.

The audience is narrow and that is a feature. This is for engineers who already have Charles installed and licensed, who already know how to enable its web interface, and who want an agent to answer questions like which host is returning the most 500s in this session. It is not for someone looking for a proxy to install from scratch. The README's prerequisites list Python 3.10+, Charles Proxy running locally, the Charles Web Interface enabled, and Charles listening on 127.0.0.1:8888.

How the MCP server talks to Charles and what the agent actually sees

The architecture is a control-plane bridge, not a packet engine. charles-mcp does not intercept traffic itself. Charles does the capturing, and the server drives Charles through its web interface over HTTP. The pyproject dependencies confirm the shape of that: httpx for the control-plane calls, pydantic for the structured models, jmespath for filtering, plus defusedxml, brotli, zstandard and protobuf for decoding the payloads that come back.

The agent-facing surface is a set of tools. The README's recommended live path is start_live_capture, then group_capture_analysis, then query_live_capture_entries, then get_traffic_entry_detail, then stop_live_capture. The history path is list_recordings, analyze_recorded_traffic, group_capture_analysis with source="history", then get_traffic_entry_detail. Both paths are deliberately ordered cheapest-first: group and summarize, then query, then fetch one detail.

There is a real design decision in how much a summary call returns. The README states that read_live_capture and peek_live_capture now return only route-level summary fields such as host, method, path and status. That is a token-budget choice, and it means an agent cannot answer a question about a request body from a peek. It has to call get_traffic_entry_detail. If your workflow is mostly body inspection, the summary-first default is overhead rather than savings.

v3.0 extended the tool surface toward reverse-engineering work: import, query, decode, replay, signature-candidate analysis and live reverse sessions, with state kept in SQLite under CHARLES_REVERSE_STATE_DIR. That is a much larger claim than traffic viewing, and the README describes it as a direction rather than a finished workflow.

Installing charles-mcp and running a first live capture

The README says you do not need to clone the repository or create a virtual environment by hand. You need uv, and the server runs through uvx. Before any of that, Charles has to be running with its web interface on. In Charles, open Proxy, then Web Interface Settings, tick Enable web interface, and set the username to admin and the password to 123456, which are the defaults the README uses throughout.

For Claude Code CLI, the README gives a single registration command. The env block sets the Charles credentials and explicitly disables lifecycle management, so the MCP server will not shut down your Charles process when it exits.

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

For Claude Desktop, Cursor, Windsurf or any client that reads a JSON config, the same entry goes under mcpServers. The README's auto-install prompt tells the agent to read an existing config first, add the charles key, and write it back without overwriting other servers.

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

Codex CLI uses TOML instead, with the environment variables in their own table.

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

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

To check that the package starts at all, the README's verification step is to run uvx charles-mcp, wait a few seconds, and terminate the process. If it starts without import errors, the install is considered good. Restart the MCP client afterwards so it picks up the new server, and confirm Charles is running with the web interface enabled before you ask the agent for anything.

The first real use is a bounded live capture. The README's live path starts with start_live_capture, then group_capture_analysis to find hotspots, then query_live_capture_entries, then get_traffic_entry_detail for one request, then stop_live_capture. CHARLES_MAX_STOPTIME defaults to 3600, which the README describes as the maximum duration for a bounded recording. If you would rather point the agent at a capture you already saved, skip to list_recordings and analyze_recorded_traffic.

Where charles-mcp breaks down or is the wrong tool

The largest constraint is that Charles is a dependency, not a component. charles-mcp cannot capture anything on its own. If Charles is not installed, not running, or does not expose its web interface, the server has nothing to talk to. That rules it out for headless CI runs, for Linux servers without a desktop session, and for anyone who wants interception as a library rather than a GUI application.

The lifecycle flag is the second sharp edge. CHARLES_MANAGE_LIFECYCLE defaults to false, and the README recommends keeping it there unless you specifically want the MCP server to control Charles startup and shutdown. Setting it to true means the server may stop a Charles process you were using for something else. The README's own wording is that you should not let it close your Charles process on exit unless that is what you intend.

Third, the default tool surface shrank in v3.0.3. Legacy aliases such as filter_func, proxy_by_time and list_sessions are no longer exposed by default, and you have to opt back in with create_server(expose_legacy_tools=True) or CHARLES_EXPOSE_LEGACY_TOOLS=true. Any prompt, script or saved agent workflow written against the older aliases will fail until you either enable that compatibility switch or rewrite the calls. The README points to docs/migrations/legacy-tools.md as the authoritative migration note, which is a sign the maintainers expect this to bite people.

Fourth, the reverse-analysis tooling added in v3.0 is described as a direction, not a settled feature. The README lists import, decode, replay, signature-candidate analysis and live reverse sessions, and mentions a SQLite state directory, but it does not document rollback or recovery for that state. Treat the reverse workflow as the least proven part of the project.

charles-mcp against mitmproxy-based MCP servers

The obvious alternative family is mitmproxy plus an MCP wrapper, which appears in the related searches as mitmproxy-mcp. The difference is architectural rather than cosmetic. mitmproxy is a console and Python library, so a wrapper around it can run headless, script interception with Python addons, and drive capture from a terminal with no GUI at all. charles-mcp inherits the opposite model: a desktop application with a web interface, driven over HTTP.

That difference decides your use case. If you need interception inside a container, on a build machine, or under a script that starts and stops the proxy itself, mitmproxy is the more natural base because the proxy is already scriptable. If your team already owns Charles licenses, already trusts its certificate handling and its GUI for manual inspection, and wants an agent to read the same sessions a human is looking at, charles-mcp keeps you in that tool instead of asking you to rebuild your workflow around a different proxy.

A practical consequence: with charles-mcp, the human and the agent look at one capture. You can watch the session in Charles while the agent summarizes it. A headless mitmproxy setup usually means the capture exists only as files or a stream, and the human inspects it after the fact. Neither is better in the abstract. They are different working styles, and charles-mcp only makes sense if you are on the desktop side of that split.

Maintenance status, licence and what an upgrade costs

The repository is not archived. Its last push was on 2026-06-23, which is under six months before today, so the project has been touched recently. The most recent release listed is v3.1.0rc1, published the same day as that push, and the release before it is v3.0.3 from 2026-04-21. That release candidate status matters: the newest version is a pre-release, so a plain install of charles-mcp through uvx will not necessarily land on it unless you ask for it explicitly. The pyproject version field also reads 3.1.0rc1.

The README carries a maintenance notice dated 2026-04-21 stating that the repository's public Git history was reorganized on that date, and that anyone who cloned before it should re-clone rather than merge or push from an old local clone. If you vendor this project or maintain a fork, that is a concrete upgrade hazard: your fork's history may no longer share a base with upstream, and a merge could reintroduce stale history.

The licence is MIT, declared both in pyproject.toml and as a LICENSE file at the repository root, with setuptools configured to ship the licence file. MIT is permissive and places few conditions on redistribution or modification. That is a general description of the licence, not legal advice, and it says nothing about the separate licence you need for Charles Proxy itself, which is a commercial product and is not covered by this project's licence.

Upgrade cost has two components. The Python side is ordinary: change the version you pin and rerun, since the runtime dependencies are a short list of well-known packages. The tool-contract side is where upgrades actually hurt. v3.0.3 tightened the default surface to 31 canonical tools and hid the legacy aliases, so an upgrade can silently break an agent workflow that still calls filter_func, proxy_by_time or list_sessions. The README says contract tests were added to keep tool descriptions from drifting away from the documentation, which helps you detect the drift but does not remove the work of updating your prompts.

Editorial conclusion

Adopt charles-mcp if you already drive Charles Proxy by hand and want an agent to summarize live or recorded traffic without dumping raw capture dictionaries into context. Skip it if you do not run Charles, if you need a proxy that captures without a GUI, or if you want a general HTTP interception library rather than a bridge to one desktop tool. Before relying on it, verify three things yourself: that your Charles build exposes the Web Interface at the credentials you configured, that CHARLES_MANAGE_LIFECYCLE is false unless you actually want the server to stop your Charles process, and that the canonical tool set in docs/contracts/tools.md matches the tools your client sees, since v3.0.3 removed the legacy aliases from the default surface.

Frequently asked questions

Official sources

1. heizaheiza/Charles-mcp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases