charles-mcp
Provides read-only, live access to the HTTP(S) traffic Charles Proxy is currently capturing, allowing agents to list recent requests, inspect request/response headers, timing, TLS details and (optionally) bodies, search traffic, and get session summaries — with credentials redacted and host allowlists limiting visibility.
Documentation: docs/ · Source: github.com/chancecreate/charles-mcp
charles-mcp lets MCP clients like Claude Code, Codex and Cursor read the HTTP(S) traffic that Charles Proxy is capturing, while it's being captured.
A small bridge runs inside Charles and listens to every request and response through Charles's own proxy API. Your agent asks something like "why is the checkout call returning 422?" and answers it from traffic that's actually on the wire. You don't need to export sessions, and the Web Interface isn't polled.
The key features are:
Live: events come out of Charles as requests start, get responses and finish, with Charles's own timestamps.
Native: hooks Charles's public listener API, so no Charles bytecode is modified.
Private by default: credentials are redacted twice, bodies stay off until you enable them, and the bridge only answers authenticated local clients.
Safe for Charles: queues are bounded and nothing blocks a proxy thread. If the bridge stops, Charles carries on.
Token-efficient: compact, paginated, typed tool results, with cursors for "what's new since last time?"
Read-only: no replay, no traffic modification, no certificate access. It's an inspection tool.
Quickstart
No build tools needed. You need Charles Proxy 4.6.x on Windows (4.6.8 is the latest) and Python 3.11+.
Download
charles-mcp-<version>-windows.zipfrom the latest release and unzip it.Close Charles, then double-click
Install.cmd. Click Yes when Windows asks for permission.Start Charles. If you use Claude Code, it's already connected. Just ask about your traffic.
To remove it, double-click Uninstall.cmd.
Related MCP server: reqable-mcp
Installation from source
Requirements: Charles Proxy 4.6.x on Windows, Python 3.11+, and JDK 11+.
Build the agent and install it into Charles. Run this from an elevated PowerShell if Charles is in
Program Files. The installer backs up Charles.ini, and -Uninstall puts it back.
$ cd java && ./mvnw -B package && cd ..
$ .\scripts\install-windows.ps1Then install the MCP server:
$ pip install ./pythonExample
Connect it
Add the server to your MCP client. For Claude Code:
$ claude mcp add charles -- charles-mcpConfigs for Codex and Cursor are in examples/.
Check it
Restart Charles, browse something, then run:
$ charles-mcp status
{
"bridge_connected": true,
"charles_version": "4.6.8",
"recording": true,
"session_id": "s-cd075c67",
...
}Ask it
Your agent now has these tools:
Tool | What it does |
| Recent requests, newest first. Filter by host, method, status, URL, content type or time. Pass |
| Method, URL, headers, timing and sizes, plus the body if you ask for it. |
| Status, headers, timing, TLS details and errors, plus the body if you ask for it. |
| Searches URLs, headers and (if enabled) bodies, and returns snippets. |
| Counts by host, method and status, recent errors and totals. |
| Raw lifecycle events since a cursor. |
| Bridge health, recording state and drop counters. |
Here's a get_response result from a live capture, trimmed, with secrets already redacted:
{
"status": 200,
"state": "complete",
"headers": [
{ "name": "Content-Type", "value": "application/json; charset=utf-8" },
{ "name": "Set-Cookie", "value": "[REDACTED]" }
],
"body": {
"kind": "json",
"text": "{ \"user\": \"demo\", \"access_token\": \"[REDACTED]\", \"profile\": { \"password\": \"[REDACTED]\", \"plan\": \"free\" } }",
"untrusted": true
}
}Request bodies
Bodies are off by default. Turn them on when you need them:
$ claude mcp add charles --env CHARLES_MCP_ALLOW_BODIES=1 -- charles-mcpEven when they're on, bodies are size-capped and redacted, and binary content is never decoded into text. Captured content is also marked as untrusted, so your agent treats it as data rather than instructions.
Host filters limit what the agent can see:
# charles-mcp.toml
[charles_mcp]
allow_bodies = true
host_allowlist = ["api.example.com", "*.staging.example.com"]Every setting is listed in examples/charles-mcp.toml.
How it works
Charles 4.6.x charles-mcp your agent
┌─────────────────────────────────────┐ ┌──────────────────────┐ ┌──────────────┐
│ proxy ─▶ listener ─▶ bounded queue │ │ index ─▶ redaction │ │ Claude Code │
│ ─▶ event store ─▶ bridge ├─────▶│ ─▶ MCP tools │◀────▶│ Codex │
│ 127.0.0.1 · token auth │ TCP │ │stdio │ Cursor │
└─────────────────────────────────────┘ └──────────────────────┘ └──────────────┘Charles's bundled Java runtime can't load -javaagent, so the installer points Charles.ini at a tiny
launcher instead. The launcher starts the bridge and then hands control to Charles as usual. More detail is
in architecture and the internals notes.
Security
Your MCP client may send tool output to a cloud model, so only enable bodies for traffic you'd be fine sharing, and use host allowlists. Redaction works from header and key names and from known token formats, which means a secret with no recognisable name or shape can get through. The full threat model is in docs/security.md.
Troubleshooting
Symptom | Fix |
| Charles isn't running with the bridge. Re-run the installer and restart Charles. |
| Charles exited abruptly. Restart it. |
| Start recording in Charles. |
Requests from your app are missing | Check that the app uses Charles as its proxy, and check your host filters. |
| Your Charles version isn't supported yet, so the bridge stays off. Charles still runs normally. |
Development
$ cd java && ./mvnw -B verify
$ cd python && pip install -e ".[dev]" && pytestTo try the tools without Charles, run the mock bridge and point the server at its discovery file:
$ charles-mcp mock-bridge --fixture fixtures/sample-bridge.json --discovery ./mock.json
$ CHARLES_MCP_DISCOVERY_FILE=./mock.json charles-mcpSee testing and contributing.
License
This project is licensed under the terms of the MIT license.
Charles Proxy is a product of XK72 Ltd. This project isn't affiliated with or endorsed by XK72.
Available Tools
7 toolsget_requestC
Request line, headers (redacted), timing, sizes and optionally the bounded/redacted request body.
Inputs: transaction_id (required), include_body, max_body_bytes. Returns: url, body, host, port, +13 more
get_responseC
Status, headers (redacted), timing, TLS/connection info and optionally the bounded/redacted response body.
Inputs: transaction_id (required), include_body, max_body_bytes. Returns: body, error, state, status, +9 more
get_session_summaryC
Counts by host/method/status, recent errors and total sizes for indexed traffic.
Inputs: top, session_id. Returns: failed, by_host, removed, complete, +12 more
get_statusB
Bridge connectivity, Charles version, recording state, queue/drop counters and active safety settings.
Inputs: no named parameters. Returns: index, queue, settings, recording, +10 more
list_requestsB
List captured requests (compact summaries, redacted URLs) with filters and cursor pagination.
Inputs: host, after, limit, state, +8 more. Returns: note, items, matched, returned, +4 more
search_trafficB
Bounded search over redacted URLs, headers and (if enabled) bodies of recent traffic.
Inputs: query (required), host, limit, fields, +1 more. Returns: note, query, matches, bodies_searched, +2 more
watch_requestsB
Raw lifecycle events (request_created ... response_complete/failed) since a cursor. This is a pull: call it again with next_after to get newer events; it does not stream.
Inputs: after, limit. Returns: events, next_after, events_lost, bridge_connected
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
The tools mostly target distinct inspection needs: status, compact listing, single request, single response, search, aggregate summary, and lifecycle events. Some overlap exists between list_requests, search_traffic, and watch_requests, but their descriptions clarify filtering, bounded search, and cursor-based event pulling respectively.
All names use consistent snake_case and a clear verb_noun pattern such as get_status, list_requests, get_request, and search_traffic. The set is predictable and easy to scan.
Seven tools is well-scoped for a traffic inspection server, covering listing, detail views, search, summary, status, and event watching without obvious redundancy. Each tool has a clear place in the inspection workflow.
The surface covers the core read-only inspection lifecycle, including status, captured requests, request/response details, search, summary, and live event polling. It lacks control or maintenance operations such as starting/stopping recording, clearing traffic, or exporting captures, but those may be intentionally out of scope.
Maintenance
Related MCP Connectors
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Related MCP Servers
- AlicenseBqualityCmaintenanceIntegrates 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.18330MIT
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server that brings Reqable's captured HTTP traffic into Claude Code conversations, enabling querying, searching, waiting for, and analyzing requests without requiring Reqable Pro.7MIT

ProxyKit-mcpofficial
AlicenseBqualityBmaintenanceMCP server for ProxyKit — drive a local HTTP(S) debugging proxy from Claude, Cursor, and any MCP host.50MIT- AlicenseBqualityBmaintenanceEnables 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.47MIT