Skip to main content
Glama

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+.

  1. Download charles-mcp-<version>-windows.zip from the latest release and unzip it.

  2. Close Charles, then double-click Install.cmd. Click Yes when Windows asks for permission.

  3. 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.ps1

Then install the MCP server:

$ pip install ./python

Example

Connect it

Add the server to your MCP client. For Claude Code:

$ claude mcp add charles -- charles-mcp

Configs 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

list_requests

Recent requests, newest first. Filter by host, method, status, URL, content type or time. Pass after to get only new ones.

get_request

Method, URL, headers, timing and sizes, plus the body if you ask for it.

get_response

Status, headers, timing, TLS details and errors, plus the body if you ask for it.

search_traffic

Searches URLs, headers and (if enabled) bodies, and returns snippets.

get_session_summary

Counts by host, method and status, recent errors and totals.

watch_requests

Raw lifecycle events since a cursor.

get_status

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-mcp

Even 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

discovery file not found

Charles isn't running with the bridge. Re-run the installer and restart Charles.

stale discovery file

Charles exited abruptly. Restart it.

recording: false

Start recording in Charles.

Requests from your app are missing

Check that the app uses Charles as its proxy, and check your host filters.

agent_state: unsupported

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]" && pytest

To 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-mcp

See 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 tools
get_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

    B3.4/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    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
      330
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Read-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.
      7
      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