mitmweb-mcp

One UI. You watch it, your AI reads it.

English · 简体中文

An MCP server that reads the mitmweb session you are already running — the same flows, the same window, the same moment.

You keep the mitmweb UI open and drive the browser yourself. Your AI assistant sees exactly what you see, and can search it, diff it, replay it, and turn it into a runnable scraper.

                     ┌──────────────► browser UI      (you)
  browser ──proxy──► mitmweb (:8080 proxy / :8081 API+UI)
                     └──────────────► mitmweb-mcp ───► AI assistant
                          one process · one flow list

Why this exists

Other mitmproxy MCP servers spin up their own headless proxy. That gives you two separate capture sessions: the one you are looking at, and the one the AI is looking at. To reconcile them you have to either chain the two proxies (longer path, two TLS hops, doubled latency) or accept that the two views disagree.

mitmweb-mcp takes a different route. The insight is that mitmweb's own frontend is just an HTTP client — the flow list you see in the browser comes from GET /flows.json, and clicking into a body calls GET /flows/<id>/response/content.data. That REST API has always been there; nobody treats it as an API.

So this server starts no proxy at all. It is a second, parallel client of the mitmweb you already have. Three properties fall directly out of that architecture, with no synchronisation machinery needed:

1. What the UI shows is what the AI reads. One process, one in-memory flow list.

2. Zero added latency. Nothing is inserted into the request path. Your browsing feels exactly as it did before.

3. If the MCP server dies, capture keeps running. It is only a reader.

Related MCP server: whistle.agent-mcp

Safety model: read-only and append-only

Nine of the ten tools are plain GET requests and cannot alter your session. replay_flow does not modify existing flows either — it re-sends a request, which appends a new flow. The worst case is a few extra rows; nothing you are looking at can silently change or disappear.

This boundary is published, not just documented: the nine readers carry readOnlyHint: true, so a client can decide on its own to run them without asking. replay_flow is marked destructiveHint: true — it appends to your session, but what it puts on the wire is whatever was captured, and replaying a DELETE deletes something. It should be the one tool that stops and asks.

There is deliberately no clear_flows tool. Wiping the session is destructive and irreversible, it is one click in the UI, and there is no reason to hand an AI that button.

Install

Requires Python ≥ 3.10 and mitmproxy ≥ 10 on your PATH.

pip install mitmweb-mcp

Or from source:

git clone https://github.com/numb747/mitmweb-mcp
cd mitmweb-mcp
pip install -e .

Setup

1. Start mitmweb with a fixed token

mitmweb generates a random web password at every launch, which this server has no way to discover. Pin it:

mitmweb --listen-port 8080 --set web_password=YOUR_SECRET_TOKEN

• 8080 is the proxy port — point your browser here (replays go through it too)

• 8081 is the UI + API — you watch this, and so does the MCP server

Trust mitmproxy's CA once so HTTPS works. Firefox accepts the http://mitm.it flow or an import of ~/.mitmproxy/mitmproxy-ca-cert.pem. Chrome on Linux does not — it reads the shared NSS database, so use certutil instead:

certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n mitmproxy \
         -i ~/.mitmproxy/mitmproxy-ca-cert.pem

Optionally start with a cleaner view: --set view_filter='!~a & !~d googleapis.com'. Note that view_filter applies to /flows.json as well, so it narrows what this server sees, not just the UI.

contrib/ has a mitmweb addon that launches a dedicated Chrome pointed at the proxy, plus mitm-start / mitm-stop scripts — optional, but it turns the whole thing into one command.

2. Register the MCP server

Claude Code:

claude mcp add mitmweb -s user \
  -e MITMWEB_URL=http://127.0.0.1:8081 \
  -e MITMWEB_TOKEN=YOUR_SECRET_TOKEN \
  -e MITMPROXY_PORT=8080 \
  -- mitmweb-mcp

Claude Desktop (claude_desktop_config.json) or any MCP client:

{
  "mcpServers": {
    "mitmweb": {
      "command": "mitmweb-mcp",
      "env": {
        "MITMWEB_URL": "http://127.0.0.1:8081",
        "MITMWEB_TOKEN": "YOUR_SECRET_TOKEN",
        "MITMPROXY_PORT": "8080"
      }
    }
  }
}

Restart your MCP client, then ask it to run status to confirm the connection.

Tools

Flow ids can be the 8-character short form that list_flows returns — they are matched by prefix.

Three design details worth knowing

Static assets are excluded by default. A modern page produces hundreds of flows of which maybe five matter. list_flows applies the equivalent of mitmproxy's !~a filter unless you pass include_assets=True. Binary bodies are never decoded into mojibake; you get <binary image/png, 8090 bytes, omitted> instead.

Your UI actions are usable as input. This is the payoff of sharing one session, and no headless design can offer it:

• list_flows(marked_only=True) — mark a few flows in the mitmweb UI, and the AI analyses only those.

• list_flows(since_seconds=15) — you just clicked a button; this isolates exactly what that click triggered.

Replay goes through your proxy. mitmweb's native replay endpoint is protected by Tornado's XSRF, whose cookie is only issued to the /updates websocket. Rather than maintain a websocket for that, replay_flow re-sends the request through your own proxy — so the result lands in your UI anyway, and you gain capabilities the native replay does not have: TLS/JA3 fingerprint impersonation via curl_cffi, arbitrary header and body rewriting, and allow_redirects=False so every hop stays visible.

A worked example

1 — Find the endpoint behind something you can see

"The order number SO20260910 is on this page. Which request returned it?"

search_flows("SO20260910")   → POST /api/order/list
inspect_flow("a3f21b8c")     → signing headers, body shape, equivalent curl

2 — Work out which parameters are signed

Trigger the same action twice, then:

diff_flows("a3f21b8c", "c44a48f7")

{
  "same_endpoint": true,
  "query_diff": { "changed": { "nonce": { "a": "aaa", "b": "bbb" } } },
  "body_diff":  { "changed": { "sign":    { "a": "1111", "b": "2222" },
                               "meta.ts": { "a": 1000,   "b": 2000   } } }
}

Identical fields are omitted, so what remains is the answer: the signature covers a nonce and a timestamp. page and meta.ver never varied, so they are not part of it.

3 — Confirm it reproduces outside the browser

replay_flow("a3f21b8c")                     → same 200, no browser involved
replay_flow("a3f21b8c", body={"page": 2})   → probe paging and edge cases

Every replay appears in your UI as you go.

4 — Ship it

generate_code(["a3f21b8c"], framework="curl_cffi")

#!/usr/bin/env python3
"""Generated by mitmweb-mcp from captured traffic.

Adapt as needed: add paging loops, concurrency, retries, error handling."""
from curl_cffi.requests import Session

IMPERSONATE = 'chrome'


def main() -> None:
    with Session(impersonate=IMPERSONATE) as s:

        # --- 1. POST /api/order/list (originally returned 200) ---
        r1 = s.post(
            'https://example.com/api/order/list',
            params={'page': '1'},
            headers={'Authorization': 'Bearer ...', 'Content-Type': 'application/json'},
            json={'page': 1, 'sign': '1111'},
        )
        print("1.", r1.status_code, r1.text[:200])


if __name__ == "__main__":
    main()

Pass several ids to generate a multi-step script — the requests share one Session, so a "log in, then call the API" sequence carries its cookies across.

Scope

This server is the analysis layer. Capture, live interception with breakpoints, and clearing the session stay in the mitmweb UI, where they belong — interception in particular is inherently interactive and there is nothing to gain from proxying it through an AI.

For unattended bulk capture, use mitmdump with an addon script; that is a different job from the one this tool does.

Development

git clone https://github.com/numb747/mitmweb-mcp
cd mitmweb-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

ruff check .
python tests/test_e2e.py     # needs mitmproxy on PATH and internet access

The end-to-end test launches a real mitmweb on ports 18080/18081, pushes traffic with known marker values through it (including the same endpoint called twice with only nonce/sign/ts differing, to exercise diff_flows), then drives every tool over a real MCP stdio session. It asserts 56 behaviours, including that generated code compiles and that diff_flows omits fields which did not change.

Two things that will bite you

GET /flows/<id> returns 405. /flows.json is the only list endpoint and it returns everything, at roughly 2.6 KB per flow. The 2-second TTL cache is therefore a correctness-of-cost requirement, not a micro-optimisation. Similarly, search_flows fetches bodies concurrently — serially it would be hundreds of round-trips.

FastMCP pre-parses JSON string arguments. A parameter annotated str that receives a valid JSON string gets parsed into a dict before validation, which then fails with Input should be a valid string. This is why replay_flow annotates headers and body as dict | str | None.

Contributing

Issues and pull requests are welcome. Please run ruff check . and the end-to-end test before opening a PR.

License

MIT — see LICENSE.

Acknowledgements

Built on mitmproxy and curl_cffi.