Charles MCP Server

English README | Документація | Посібник для агентів | Мапінг і перезапуск Charles | Контракт інструментів | AGENTS | Сценарії для агента | Встановлення для команди

Дайте ШІ-агенту доступ до Charles Proxy. Агент сам знаходить потрібні запити мобільного застосунку, пояснює, що пішло не так, і підміняє відповіді для тестування — без копіювання трафіку в чат і без ручних правил у Charles.

Навіщо

Коли тестуєш мобільний клієнт через Charles, більшість часу йде на рутину:

• знайти серед сотень записів один запит і скопіювати його в чат з агентом;

• підмінити одне поле у відповіді, а Map Local вміє лише «один файл на весь URL»: не розрізняє POST-запити з різним action у тілі й завжди віддає 200;

• перевірити екран помилки, порожній стан чи повільний ендпоінт — і не забути потім усе вимкнути.

charles-mcp — MCP-сервер, через який агент (Claude Code, Cursor, Codex, Kiro та інші MCP-клієнти) робить це сам: читає сесію Charles, знаходить запит, будує мок зі справжньої відповіді, змінюючи лише названі поля, і перевіряє, що застосунок отримав підмінену відповідь.

Related MCP server: mitmproxy-mcp

Що вміє

• Читати трафік стисло. Агент спершу бачить групи й короткі зведення, а не сирий дамп, і відкриває один запит лише тоді, коли треба. Працює і з живою сесією, і зі збереженими .chlsj.

• Підміняти відповіді за тілом запиту. Локальний диспетчер за одним правилом Map Remote розрізняє запити за методом, шляхом, query і полями тіла ({"action": "get_balance"}). Режими: правка полів справжньої відповіді або фікстура з будь-яким статусом (500, 401) і затримкою.

• Моки — це дані, а не код. Правила й фікстури лежать у ~/charles-mocks, поза репозиторіями; у Charles налаштовується одне правило на домен.

• Реверс-аналіз. Імпорт сесій, декодування тіл (зокрема protobuf), повтор запиту зі змінами, пошук полів-підписів.

• Безпечні значення за замовчуванням. Не очищає сесію Charles, не пише його конфіг, поки Charles працює, і вимикає Map Remote, який увімкнув сам.

Як це працює

Застосунок ходить у мережу через Charles, як завжди. Сервер читає сесію Charles через його Web Interface. Для моків Charles одним правилом Map Remote відправляє запити домену в локальний диспетчер: той відповідає за правилом (фікстура або правка справжньої відповіді), а все без правила пропускає на справжній сервер без змін. Кожна відповідь несе заголовок X-Charles-MCP-Rule, тож агент перевіряє результат по свіжому трафіку.

Приклад

Ви: На екрані гаманця баланс 10.50. Зроби, щоб get_balance повертав 0, а init — помилку 500.

Агент:

1. start_live_capture і mock_discover_variants — бачить POST /api/v1/wallet з двома варіантами action: init і get_balance.

2. mock_rule_create_from_entry двічі: для get_balance — правка /data/balance у справжній відповіді, для init — знята відповідь зі статусом 500.

3. mock_dispatcher(action="start"); ви оновлюєте екран.

4. query_live_capture_entries(response_header_name="X-Charles-MCP-Rule") — відповіді прийшли від обох правил, решта запитів пішла на сервер без змін.

Швидкий старт

1. Увімкніть Charles Web Interface

У Charles відкрийте: Proxy -> Web Interface Settings

Перевірте, що:

• позначено Enable web interface;

• ім'я користувача admin;

• пароль 123456.

Значення admin / 123456 використовуються за замовчуванням в усіх прикладах. Для справжньої роботи задайте свій пароль і передайте його через CHARLES_USER / CHARLES_PASS.

Де розташований пункт меню:

Вікно налаштувань:

Ще два налаштування Charles, обидва робляться один раз:

• Виключіть власні запити сервера із запису. Відкрийте Proxy -> Recording Settings -> Exclude, натисніть Add і вкажіть Host control.charles, решту полів залиште порожніми. Діє одразу, без перезапуску. Кожен виклик інструмента вивантажує сесію через проксі Charles; без цього виключення Charles записує кожне вивантаження з усією сесією як тілом, тож сесія зростає з кожним викликом (зі 100 КБ до 2 ГБ за один тестовий прогін), а інструменти сповільнюються до десятків секунд. Сервер попереджає про це через charles_records_own_exports.

• Увімкніть SSL Proxying для хостів, які хочете читати. Відкрийте Proxy -> SSL Proxying Settings, додайте хост API і переконайтеся, що пристрій довіряє кореневому сертифікату Charles. Без цього Charles записує HTTPS-з'єднання як один непрозорий тунель, і інструментам нема чого показати — ні шляхів, ні тіл; вони повідомляють про це попередженням ssl_proxying_off.

2. Встановіть і налаштуйте MCP-клієнт

Потрібен лише uv. Клонувати нічого не треба: uvx сам завантажить сервер із цього репозиторію, один раз збере його й закешує (якщо ваш Python старіший за 3.10, uv підтягне свій). Перевірте, що він запускається:

uvx --from git+https://github.com/ExQA/charles-mcp charles-mcp --selftest

Команда виведе версію й кількість інструментів і завершиться рядком OK.

Не ставте charles-mcp з PyPI (uvx charles-mcp, pip install charles-mcp): це інший, старіший проєкт (upstream 3.0.3) без інструментів моків.

Плагін для Claude Code (сервер і skill)

У Claude Code:

/plugin install charles-mcp --marketplace ExQA/charles-mcp

У Claude Code, старішому за 2.1.275, спершу виконайте /plugin marketplace add ExQA/charles-mcp, потім /plugin install charles-mcp@charles-mcp. Плагін спитає логін і пароль Charles Web Interface (пароль зберігається в системному сховищі ключів), додасть сервер і skill charles-proxy-qa, який підказує Claude, коли звертатися до Charles і в якому порядку викликати інструменти. Змінити облікові дані згодом можна командою /plugin configure charles-mcp@charles-mcp.

Claude Code CLI (лише сервер)

claude mcp add charles --scope user \
  -e CHARLES_USER=your-login -e CHARLES_PASS=your-password -e CHARLES_MANAGE_LIFECYCLE=false \
  -- uvx --from git+https://github.com/ExQA/charles-mcp charles-mcp

Claude Desktop / Cursor / Kiro / загальний JSON-конфіг

{
  "mcpServers": {
    "charles": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ExQA/charles-mcp", "charles-mcp"],
      "env": {
        "CHARLES_USER": "your-login",
        "CHARLES_PASS": "your-password",
        "CHARLES_MANAGE_LIFECYCLE": "false"
      }
    }
  }
}

Десктопні застосунки не завжди бачать PATH вашої оболонки: якщо сервер не стартує, впишіть у command повний шлях, який виводить which uvx. Kiro читає .kiro/settings/mcp.json у проєкті (він має перевагу) або ~/.kiro/settings/mcp.json.

Codex CLI

[mcp_servers.charles]
command = "uvx"
args = ["--from", "git+https://github.com/ExQA/charles-mcp", "charles-mcp"]

[mcp_servers.charles.env]
CHARLES_USER = "your-login"
CHARLES_PASS = "your-password"
CHARLES_MANAGE_LIFECYCLE = "false"

Skill в інших агентах

plugin/skills/charles-proxy-qa — звичайний skill у форматі SKILL.md: скопіюйте теку туди, звідки ваш агент завантажує skills (для Codex це ~/.codex/skills/). Він працює з будь-яким із конфігів вище.

Оновлення і фіксація версії

uvx зберігає зібрану версію. Щоб отримати найновішу, запустіть перевірку з --refresh і перезапустіть агента:

uvx --refresh --from git+https://github.com/ExQA/charles-mcp charles-mcp --selftest

Щоб лишатися на одному релізі, зафіксуйте його в кожному конфігу: git+https://github.com/ExQA/charles-mcp@v3.1.0rc2.

З вихідного коду або офлайн

Для розробки або щоб запускати саме заблоковані версії залежностей:

git clone https://github.com/ExQA/charles-mcp.git
cd charles-mcp && uv sync --locked
uv run charles-mcp --selftest

У конфігах вище замініть uvx і його аргументи на "command": "uv", "args": ["run", "--project", "<PATH>", "charles-mcp"], де <PATH> — абсолютний шлях до теки. Для машин без доступу до мережі є офлайн-архів із залежностями: docs/team-installation.uk.md.

Автовстановлення через AI-агента

Для локальної копії або офлайн-архіву дайте агенту промпт з INSTALL-PROMPT.md. Він встановить сервер із теки, перевірить збірку через --selftest і додасть сервер у конфіг вашого MCP-клієнта, не чіпаючи інших серверів.

Вимоги

• uv (за потреби сам підтягне Python 3.10+)

• запущений локально Charles Proxy

• увімкнений Charles Web Interface

• проксі Charles слухає 127.0.0.1:8888

Рекомендоване значення за замовчуванням — CHARLES_MANAGE_LIFECYCLE=false. Не дозволяйте MCP-серверу закривати ваш Charles, якщо ви явно не хочете, щоб він керував запуском і зупинкою Charles.

Змінні оточення

Рекомендовані сценарії

Live-аналіз

1. start_live_capture

2. group_capture_analysis

3. query_live_capture_entries

4. get_traffic_entry_detail

5. stop_live_capture

Цей шлях дозволяє спершу знайти гарячі точки з мінімальною витратою токенів, а потім розкрити один підтверджений запит.

Аналіз історії

1. list_recordings

2. analyze_recorded_traffic

3. group_capture_analysis(source="history")

4. get_traffic_entry_detail

Цей шлях підходить, щоб переглянути збережені записи і потім заглибитися в обрані запити.

Підміна відповідей через Map Local

Як влаштовані правила в Charles, коли і як Charles перезапускається, відкат і діагностика — у docs/charles-mapping.uk.md.

1. mock_setup_host — один раз на хост: створює <CHARLES_MOCK_DIR>/<host>/ і правила Charles. З apply=true (Charles має бути закритий) записує їх у конфіг Charles, інакше повертає інструкцію для ручного налаштування.

2. start_live_capture + query_live_capture_entries — знайти справжню відповідь.

3. mock_create_from_entry з правками patches у форматі JSON Pointer (або mock_write, щоб написати відповідь з нуля).

4. Застосунок повторює запит; перевірте результат через query_live_capture_entries(response_header_name="X-Charles-Map-Local").

5. mock_remove — повернутися до справжнього сервера (файл іде в архів, а не видаляється); mock_set_enabled(false) — призупинити всі моки.

Мок — це просто файл за шляхом <CHARLES_MOCK_DIR>/<host>/<шлях запиту>. Доки файл існує, Charles віддає його і перечитує на кожен запит; якщо файлу немає, запит іде на справжній сервер.

Обмеження Map Local:

• статус відповіді завжди 200;

• query string і HTTP-метод ігноруються, тому всі варіанти одного шляху отримують той самий файл;

• /users і /users/42 не можна замокати одночасно: users не може бути водночас файлом і каталогом.

Налаштування також додає правило Rewrite, яке віддає моки як application/json: Charles позначає файли без розширення як text/plain.

Багато шляхів і action: правила диспетчера

Використовуйте для справжнього API: багато шляхів, POST-запити, де операцію обирає поле action, і те саме API на кількох хостах (dev, stage тощо). Map Local такі запити не розрізняє, диспетчер розрізняє. Обґрунтування — в ADR-0001.

Правило в Charles ставиться один раз на домен і потребує перезапуску Charles (або ручного введення в UI без перезапуску). Інструменти самі Charles не закривають і не запускають: порядок дій, що втрачається і як відкотити — у docs/charles-mapping.uk.md.

Один раз на домен. mock_route_setup(host="*.example.com", path="/api/*") заводить маршрут і повертає одне правило Map Remote для Charles: https://*.example.com/api/* → локальний диспетчер із порожнім шляхом призначення (Charles зберігає вихідний шлях) і ввімкненим «Preserve host header». apply=true записує його, доки Charles закритий. Після цього всі шляхи, action і хости під маршрутом — лише дані, а запити без правила йдуть на справжній сервер без змін.

На кожну сесію.

1. start_live_capture, потім пройдіть сценарій у застосунку.

2. mock_discover_variants(source="live", capture_id) показує всю сесію: метод × хост × шлях × значення action (null для GET) з кількістю, прикладами entry_id і статусами. Фільтри — host_contains / path_contains.

3. На кожну правку, яку просить користувач: mock_rule_create_from_entry(entry_id, match_body_fields=["/action"], response_patches=[...], request_patches=[...]).

   • mode="patch" (за замовчуванням): відповідає справжній сервер, змінюються лише вказані поля запиту й відповіді.

   • mode="fixture": знята відповідь із правками і будь-яким status, наприклад 500, без звернення до сервера.

   • status підміняє код відповіді, delay_ms затримує її (0–60000 мс) — для перевірки лоадерів і тайм-аутів, request_headers задає або видаляє заголовки запиту перед відправкою.

   • Сегменти шляху, що залежать від платформи чи версії застосунку, замінюйте на * через match_path, наприклад /api/*/wallet.

   • За замовчуванням правило діє на всіх хостах маршруту (host_scope="any"); host_scope="exact" або host="stage.example.com" звужують його, і правило для конкретного хоста перемагає загальне.

   • Повторне прохання для того самого варіанта доповнює його правило (merge=true); правка того самого поля замінює попередню.

4. mock_dispatcher(action="start"), потім повторіть дії в застосунку.

5. Перевірте через query_live_capture_entries(response_header_name="X-Charles-MCP-Rule"): у заголовку id правила або passthrough.

Зберігання в <CHARLES_MOCK_DIR>/_rules/: routes.json (маршрути), _any/ (правила для будь-якого хоста або шаблону хоста), <host>/ (правила для одного хоста), фікстури поруч із правилами як <rule_id>.body. Диспетчер перечитує їх на кожен запит, тому правки діють одразу. Він пересилає лише запити, покриті маршрутом, слухає 127.0.0.1 і має працювати, доки в Charles увімкнене правило Map Remote; для постійної роботи запустіть у терміналі uvx --from git+https://github.com/ExQA/charles-mcp charles-mcp-dispatcher --port 18080. Маршрут на весь хост (/*) пропускає через диспетчер і статику, і WebSocket: завантаження буферизуються, а WebSocket не підтримується, тому краще вказувати префікс API.

⚠️ Фікстури — це зняті справжні відповіді, у них можуть бути персональні та платіжні дані. Тримайте CHARLES_MOCK_DIR поза репозиторіями і нікому не пересилайте; діліться описами правил із синтетичними даними.

Каталог інструментів

Цей README описує весь публічний набір інструментів.

Інструменти live-захоплення

Інструменти аналізу

Інструменти історії

Інструменти стану і керування

⚠️ reset_environment закриває Charles, перезаписує його конфіг із бекапа і видаляє каталог збережених записів. Викликайте його лише свідомо.

Інструменти реверс-аналізу

Інструменти моків Map Local

Інструменти правил диспетчера

Ключова поведінка

1. За замовчуванням повертаються сирі дані

Ця версія більше не маскує вміст запитів і відповідей:

• зведення, деталі, live і history повертають сирі значення;

• якщо потрібне маскування, його має робити MCP-клієнт або агент.

⚠️ Токени, cookie і персональні дані з трафіку потрапляють у контекст моделі як є. Використовуйте тестові акаунти і стенди.

2. Спочатку зведення, потім деталі

Спершу викликайте group_capture_analysis, query_live_capture_entries або analyze_recorded_traffic, і лише для підтвердженої цілі — get_traffic_entry_detail.

Не вмикайте include_full_body=true без явної причини.

3. Вивід оптимізований під бюджет токенів

Серіалізація всіх зведень і деталей полегшена:

• внутрішні поля header_map, parsed_json, parsed_form, lower_name не потрапляють у вивід інструментів;

• значення null автоматично прибираються під час серіалізації;

• якщо в детальному вигляді є full_text, надлишковий preview_text видаляється.

Значення за замовчуванням невеликі, щоб берегти контекстне вікно:

Якщо потрібен ширший огляд, більші значення так само можна передати явно.

4. Деталі з історії потребують стабільного ідентифікатора джерела

Зведення по історії повертають recording_path, зведення по live — capture_id.

Для get_traffic_entry_detail:

• в історії передавайте recording_path;

• у live передавайте capture_id.

5. Збій stop_live_capture відновлюваний

У stop_live_capture два стабільні кінцеві стани:

• status="stopped" — захоплення справді закрите;

• status="stop_failed" — короткий повтор теж не вдався, але захоплення збережене.

Якщо результат такий:

{
  "status": "stop_failed",
  "recoverable": true,
  "active_capture_preserved": true
}

означає, що захоплення так само можна читати, діагностувати і згодом зупинити повторно.

Розробка

CI пропускає зміни лише після успішного проходження ruff, mypy і pytest. Локально запускайте те саме:

python -m ruff check charles_mcp tests
python -m mypy charles_mcp
python -m pytest -q

Корисні команди для локального запуску:

python charles-mcp-server.py
python -c "from charles_mcp.main import main; main()"

Походження

Це форк heizaheiza/Charles-mcp (MIT). Форк додав підміну відповідей (Map Local і диспетчер правил), роботу з довгими сесіями та виправлення, описані в CHANGELOG.md. Подробиці — у PROVENANCE.md.

Див. також

• Документація

• Як це працює: схеми та налаштування Kiro

• English README

• Контракт інструментів