This project provides a Charles Proxy MCP server designed to integrate Charles traffic capture with AI agents, enabling structured analysis of live and historical network traffic. It targets AI agents and developers needing to programmatically inspect and analyze network requests, offering a stable, low-token, and repeatable interface for tasks ranging from basic traffic inspection to complex reverse-engineering workflows. The primary benefit is a streamlined, agent-friendly way to access and process Charles Proxy data, reducing complexity and improving efficiency for automated analysis.

How It Works

The Charles MCP Server acts as a bridge, connecting Charles Proxy's web interface to various MCP clients (e.g., Claude Code, Cursor). It offers a unified toolset for both live and historical traffic analysis, abstracting away the raw Charles data format into structured, queryable summaries. A core design principle is "summary-first, detail-on-demand," optimizing for AI context windows by providing concise overviews before allowing deeper dives into specific requests. Version 3.0 significantly expands capabilities into reverse-engineering workflows, introducing tools for session import, decoding, replay, and signature candidate discovery, aiming to close the loop for automated analysis and manipulation of network protocols.

Quick Start & Requirements

• Primary Install/Run Command: After initial setup, the server is typically invoked via uvx charles-mcp.
• Prerequisites: Python 3.10+, Charles Proxy running with its Web Interface enabled (default credentials: admin/123456). The uv package manager is required and can be installed via curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or PowerShell (Windows).
• Setup: Configuration involves adding a JSON or TOML entry to your MCP client's configuration file, or by providing a detailed prompt to an AI agent that automates detection and setup. Users who cloned the repository before April 21, 2026, must re-clone to avoid history issues.
• Links: AI-driven installation prompt available within the README.

Highlighted Details

• Reverse-Analysis Suite: Introduces tools for importing sessions, querying, decoding bodies, replaying requests, discovering signature candidates, and live reverse analysis workflows.
• Token Optimization: Output is heavily optimized, stripping null fields, internal data structures (header_map, parsed_json), and reducing default limits for fields like max_body_chars (2048) and max_items (10) to conserve AI context.
• Summary-First Approach: Tools like group_capture_analysis and query_live_capture_entries provide aggregated summaries before detailed inspection via get_traffic_entry_detail.
• Unified Semantics: Live and history analysis tools share consistent naming and behavior, simplifying agent logic.
• Legacy Tool Opt-in: Older, less efficient tools are hidden by default but can be exposed via configuration (expose_legacy_tools=True or CHARLES_EXPOSE_LEGACY_TOOLS=true).

Maintenance & Community

The project's public Git history was recently reorganized on April 21, 2026. Maintenance is handled by the current maintainer independently. No specific community channels (like Discord or Slack) are listed in the provided documentation.

Licensing & Compatibility

The license type is not explicitly stated in the provided README content. Compatibility for commercial use or closed-source linking is therefore undetermined without further information.

Limitations & Caveats

Legacy tools are not exposed by default and require explicit opt-in. The default Charles Web Interface credentials (admin/123456) are hardcoded in the configuration examples, necessitating user management for security. Users who cloned the repository prior to April 21, 2026, are advised to re-clone to ensure they have the latest, clean history. Access to historical recordings is restricted to managed directories (.chlsj files).