Charles
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
What is Charles?
Charles is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to 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 ...
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
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Integrates Charles Proxy with MCP clients to provide real-ti
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx charles-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Charles
Charles MCP Server integrates Charles Proxy — the popular HTTP/HTTPS debugging proxy — with AI assistants through the Model Context Protocol, enabling agents to capture, query, and analyse real-time and historical network traffic programmatically. It implements a summary-first philosophy: agents start with grouped capture analysis to identify interesting requests, then drill into specific entries on demand, keeping token usage low while providing deep debugging power. Security-conscious usage is supported through automatic data desensitisation and configurable body size limits.
Prerequisites
- Charles Proxy installed and running (https://www.charlesproxy.com/) — a licensed or trial copy
- Charles Proxy web interface enabled (default: http://localhost:8888/charles/proxies)
- Python 3.9 or later installed
- uv package manager for running the server via uvx
- An MCP-compatible AI client such as Claude Desktop, Cursor, or VS Code
Ensure Charles Proxy is running with the web interface enabled
Start Charles Proxy and confirm the web interface is accessible at http://localhost:8888. The default credentials are username 'admin' and password '123456'. You can change these in Charles Proxy's Preferences under Proxy > Web Interface.
Install uv if not already present
The Charles MCP server is distributed as a Python package and is best run via uvx, which is bundled with uv.
pip install uv
# or on macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | shAdd the server to your Claude Desktop configuration
Open your claude_desktop_config.json file and add the charles-mcp server entry. Set CHARLES_USER and CHARLES_PASS to match your Charles Proxy web interface credentials. Set CHARLES_MANAGE_LIFECYCLE to true if you want the MCP server to start and stop Charles Proxy automatically.
{
"mcpServers": {
"charles": {
"command": "uvx",
"args": ["charles-mcp"],
"env": {
"CHARLES_USER": "admin",
"CHARLES_PASS": "123456",
"CHARLES_PROXY_HOST": "127.0.0.1",
"CHARLES_PROXY_PORT": "8888",
"CHARLES_MANAGE_LIFECYCLE": "false",
"CHARLES_REQUEST_TIMEOUT": "10"
}
}
}
}Restart your MCP client
Save the configuration and fully restart Claude Desktop (or your chosen MCP client). The Charles MCP server will appear as connected in the MCP server list.
Start a live capture session
In your AI assistant, ask it to start a live capture. The server exposes start_live_capture, read_live_capture, peek_live_capture, stop_live_capture, and query_live_capture_entries tools for real-time traffic analysis.
Analyse traffic using the summary-first workflow
Use group_capture_analysis to get a high-level summary of traffic grouped by host or path, then drill into specific entries using get_traffic_entry_detail with the entry_id. This approach minimises token usage compared to fetching all traffic at once.
Charles Examples
Client configuration
Complete Claude Desktop configuration for Charles MCP Server with all available environment variables shown. Adjust CHARLES_USER and CHARLES_PASS to match your Charles Proxy setup.
{
"mcpServers": {
"charles": {
"command": "uvx",
"args": ["charles-mcp"],
"env": {
"CHARLES_USER": "admin",
"CHARLES_PASS": "123456",
"CHARLES_PROXY_HOST": "127.0.0.1",
"CHARLES_PROXY_PORT": "8888",
"CHARLES_REQUEST_TIMEOUT": "10",
"CHARLES_MANAGE_LIFECYCLE": "false"
}
}
}
}Prompts to try
Example prompts for debugging network traffic with Charles MCP Server.
- "Start a live capture and tell me which hosts are receiving the most requests"
- "Show me a summary of all POST requests captured in the last recording session"
- "Find any requests to api.example.com that returned a 4xx or 5xx status code"
- "Analyse the login flow: start a live capture, then stop it after I log in and show me the authentication endpoints"
- "Compare the request headers between two entries to find why one request succeeds and the other fails"
- "Identify any requests that are sending sensitive data like tokens or passwords in query parameters"Troubleshooting Charles
Connection refused error when the MCP server tries to reach Charles Proxy
Verify Charles Proxy is running and the web interface is enabled. Check CHARLES_PROXY_HOST and CHARLES_PROXY_PORT match your Charles settings. The default port is 8888. Navigate to http://127.0.0.1:8888/charles/proxies in your browser to confirm the web interface is accessible.
Authentication failure (401) when connecting to Charles web interface
Update CHARLES_USER and CHARLES_PASS in your MCP config to match the credentials set in Charles Proxy Preferences > Proxy > Web Interface. The default credentials (admin / 123456) may have been changed during Charles installation.
Response bodies are truncated or empty in traffic analysis
The server defaults to max_body_chars=2048 and include_full_body=false for token efficiency. When you need the complete body, ask the AI to call get_traffic_entry_detail with include_full_body=true on a specific entry_id rather than requesting full bodies for all traffic at once.
Frequently Asked Questions about Charles
What is Charles?
Charles is a Model Context Protocol (MCP) server that 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 It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Charles?
Follow the installation instructions on the Charles GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Charles?
Charles works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Charles free to use?
Yes, Charles is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Charles Alternatives — Similar Developer Tools Servers
Looking for alternatives to Charles? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Charles in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Charles?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.