charles-local-mcp

仅限本地的、基于配置文件的 Charles Proxy 自动化工具，适用于 macOS。同一应用服务通过 JSON CLI 和 MCP stdio 服务器暴露。

版本 0.1.2 支持 macOS 上的 Charles 4.6.8。公开包仅包含通用的 example.com 测试数据，不包含任何组织特定的主机或路径。

配置文件

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"

省略 destinationUrl 可创建仅代理的配置文件，该配置会禁用 Map Remote，同时保留确切的 SSL 主机和可选的验证 URL。当提供 destinationUrl 时，其仅限回环地址。

Map Remote 目标必须解析为回环主机。verificationUrl 为可选，必须使用 HTTPS 且不包含内嵌凭据，并且必须与 sourceHost 匹配。

Related MCP server: Charles MCP Server

命令

charles-local-mcp doctor --json
charles-local-mcp --profiles-file profiles.toml profiles validate --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

状态默认存储在 ~/Library/Application Support/charles-local-mcp。测试和集成者可以通过 CHARLES_LOCAL_MCP_HOME 或 --state-dir 将其隔离。CLI 的标准输出仅为 JSON；MCP 的标准输出仅为协议。诊断信息使用标准错误输出。

变更命令需要 macOS 和 Charles 4.6.8。设置和清理计划在 15 分钟后过期，仅可使用一次，如果状态已更改则会被拒绝。一个状态目录中只允许一个活动会话。

真实设备流程有意采用手动方式：请参阅 docs/manual-smoke.md。

安装

当本地 Rust 工具链可用时，可从 crates.io 构建：

cargo install charles-local-mcp --locked

如需在 macOS 上一键安装 MCP 客户端，请使用匹配的 GitHub Release 中的通用 .mcpb 资源。原生二进制文件和捆绑包未经 Apple 签名或公证，因此 macOS 在打开下载的资源时可能会显示安全警告。安装前请验证该 Release 中的 SHA256SUMS。该捆绑包会要求提供 TOML 配置文件，并启动 charles-local-mcp serve；配置文件对 MCP 工具保持只读。

发布维护者应遵循 docs/releasing.md。