Charles Local MCP
Guarded local Charles Proxy automation and bounded XML session evidence
Open source Open in the app JSON README (API)
About
Guarded local Charles Proxy automation and bounded XML session evidence
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- eason0in
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Last push
- 2026-08-27T13:20:17Z
- Repository state
- ativo
- Language
- Rust
- License
- Apache-2.0
- Added
- 2026-08-29 03:01:50
- Updated
- 2026-08-29 03:01:50
- Origin id
io.github.Eason0in/charles-local-mcp
README
# charles-local-mcp Local-only, profile-driven Charles Proxy automation for macOS. The same application service is exposed through a JSON CLI and an MCP stdio server. Version `0.1.3` supports Charles `4.6.8` on macOS. The public package contains only generic `example.com` fixtures and no organization-specific hosts or paths. ## Profile ```toml schemaVersion = 1 [profiles.demo] sourceHost = "app.example.com" sourcePath = "/api*" # optional Charles path pattern destinationUrl = "http://127.0.0.1:8080" sslHosts = ["app.example.com"] verificationUrl = "https://app.example.com/health" ``` Omit `destinationUrl` for a proxy-only profile that disables Map Remote while retaining the exact SSL hosts and optional verification URL. When present, `destinationUrl` is restricted to loopback addresses. Map Remote destinations must resolve to a loopback host. `verificationUrl` is optional, must use HTTPS without embedded credentials, and must match `sourceHost`. ## Commands ```console charles-local-mcp doctor --json charles-local-mcp --profiles-file profiles.toml profiles validate --json charles-local-mcp --profiles-file profiles.toml --evidence-root /absolute/path/exports session evidence --profile demo --xml-file session.xml --json charles-local-mcp --profiles-file profiles.toml setup plan --profile demo --platform android --json charles-local-mcp --profiles-file profiles.toml setup apply --token TOKEN --json charles-local-mcp setup resume --token TOKEN --json charles-local-mcp status --json charles-local-mcp cleanup plan --json charles-local-mcp cleanup apply --token TOKEN --json charles-local-mcp serve ``` State defaults to `~/Library/Application Support/charles-local-mcp`. Tests and integrators can isolate it with `CHARLES_LOCAL_MCP_HOME` or `--state-dir`. CLI stdout is JSON only; MCP stdout is protocol only. Diagnostics use stderr. Mutation commands require macOS and Charles `4.6.8`. Setup and cleanup plans expire after 15 minutes, are single-use, and are rejected if state changed. Only one active session is allowed in a state directory. ## Local XML session evidence `session evidence` reads only a selected local `.xml` file inside the configured `--evidence-root` and the selected immutable profile. If the option is omitted, the root defaults to `<state-dir>/evidence`; it is resolved only when evidence analysis is requested, so existing setup and inspection commands do not require that directory. Relative traversal and absolute paths outside the root are rejected without returning local paths. The evidence root, parent directories, and selected file must not be symbolic links. The operation uses the selected profile's exact `sourceHost` only as an internal filter. The bundle returns the profile name with `hostScope: "exact"`, a fixed HTTP method enum, per-bundle opaque route references such as `route-001`, query parameter counts, numeric status/duration, and request/response sizes when those attributes exist. Repeated raw paths receive the same opaque route reference within one bundle. Other hosts are excluded and reported only as a count. The operation never returns raw hosts, paths, query names, query values, headers, cookies, credentials, or bodies. Unknown request methods become the fixed value `OTHER`. It does not upload or persist the source session and does not write an evidence ledger. Files are limited to 10 MiB and 1,000 transactions; output is limited to 100 requests and 50 failures. DTD, DOCTYPE, and entity references are rejected. Some Charles exports include a DOCTYPE declaration; make a trusted local copy and remove the complete declaration before analysis. See [`docs/session-evidence.md`](docs/session-evidence.md) for the contract, safety boundary, limits, and stable error codes. The real-device procedure is intentionally manual: see [`docs/manual-smoke.md`](docs/manual-smoke.md). ## Install Build from crates.io when a local Rust toolchain is available: ```console cargo install charles-local-mcp --locked ``` For a one-click MCP client installation on macOS, use the universal `.mcpb` asset from the matching GitHub Release. The native binary and bundle are not signed or notarized by Apple, so macOS may show a security warning when opening a downloaded asset. Verify `SHA256SUMS` from that release before installing. The bundle asks for a TOML profiles file and starts `charles-local-mcp serve`; profiles remain read-only to MCP tools. It also asks for the XML evidence folder that is the only directory the `session_evidence` tool may read. Release maintainers should follow [`docs/releasing.md`](docs/releasing.md).