mitmproxy-mcp

MCP server for mitmproxy that lets any MCP client analyze, intercept, and replay HTTP/HTTPS traffic.

What is this

mitmproxy-mcp runs as a mitmproxy addon. It embeds an MCP server directly in the proxy process, giving AI agents access to 24 tools for traffic analysis, request replay, interception control, and proxy configuration.

All captured data stays in-memory. Sensitive values (tokens, passwords, API keys, JWTs) are automatically redacted before being sent to the AI.

Installation

git clone https://github.com/moha-abdi/mitmproxy-mcp.git
cd mitmproxy-mcp

python3.10 -m venv .venv
source .venv/bin/activate

uv pip install -e ".[dev]"

# one-time: make mitmproxy/mitmdump/mitmweb use this env
# (prevents missing addon deps like `mcp` when system mitmproxy is used)
mitmproxy-mcp install-shims --force

Requires Python 3.10+ and mitmproxy >= 10.0.0.

Agent Skill (optional)

This repo also ships a skill definition in SKILL.md for the npx skills ecosystem.

Install it with:

npx skills add moha-abdi/mitmproxy-mcp

After installing, compatible coding agents can load the mitmproxy-mcp skill and get project-specific usage guidance.

Setup

1. Configure mitmproxy

Create or edit ~/.mitmproxy/config.yaml:

scripts:
  - /absolute/path/to/mitmproxy-mcp/addon.py

mcp_transport: sse
mcp_port: 9011

2. Start mitmproxy

mitmproxy      # interactive TUI
mitmweb        # web interface
mitmdump       # headless

The MCP server starts automatically on http://localhost:9011/sse. If the command still resolves to a system install, ensure your shim directory (default ~/.local/bin) is earlier in PATH, then restart the terminal.

3. Connect your AI client

All clients connect to the same SSE endpoint. Make sure mitmproxy is running before connecting.

<details> <summary><b>OpenCode</b></summary>

OpenCode's local type bridges via supergateway. Requires Node.js.

Add to opencode.json in your project root, or ~/.config/opencode/opencode.json globally:

{
  "mcp": {
    "mitmproxy": {
      "type": "local",
      "command": ["npx", "-y", "supergateway", "--sse", "http://127.0.0.1:9011/sse"],
      "enabled": true
    }
  }
}

</details>

<details> <summary><b>Claude Code</b></summary>

Via the CLI (project-level):

claude mcp add --transport sse mitmproxy http://localhost:9011/sse

To add globally across all projects:

claude mcp add --scope user --transport sse mitmproxy http://localhost:9011/sse

Or add manually to ~/.claude.json:

{
  "mcpServers": {
    "mitmproxy": {
      "type": "sse",
      "url": "http://localhost:9011/sse"
    }
  }
}

</details>

<details> <summary><b>Cursor</b></summary>

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "mitmproxy": {
      "url": "http://localhost:9011/sse"
    }
  }
}

</details>

<details> <summary><b>Windsurf</b></summary>

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mitmproxy": {
      "url": "http://localhost:9011/sse"
    }
  }
}

</details>

<details> <summary><b>VS Code (Copilot)</b></summary>

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "mitmproxy": {
      "type": "http",
      "url": "http://localhost:9011/sse"
    }
  }
}

</details>

<details> <summary><b>Claude Desktop</b></summary>

Claude Desktop doesn't natively support SSE, so we use supergateway to bridge SSE to STDIO. Requires Node.js.

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "mitmproxy": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse", "http://127.0.0.1:9011/sse"]
    }
  }
}

</details>

<details> <summary><b>Other clients</b></summary>

Any MCP client that supports SSE transport can connect directly to:

http://localhost:9011/sse

If your client only supports STDIO, use supergateway to bridge:

npx -y supergateway --sse http://127.0.0.1:9011/sse

</details>

Tools

Flow tools (12)

Tool	Description
get_flows	List captured flows with pagination and filtering
get_flow_by_id	Get complete flow details
search_flows	Search flows by regex pattern
get_flow_request	Get request details
get_flow_response	Get response details
mark_flow	Mark a flow (same behavior as UI mark action)
unmark_flow	Remove mark from a flow
focus_flow	Move UI focus to a visible flow by ID
focus_flow_index	Move UI focus by visible list index
clear_flows	Clear all captured flows (and UI view when sync includes clear)
get_flow_count	Count captured flows
export_flows	Export flows to HAR format

Replay tools (4)

Tool	Description
replay_request	Replay a captured request as-is
send_request	Send a new HTTP request
modify_and_send	Modify a captured request and send it
duplicate_flow	Clone a flow for comparison

Replay tool flows are reflected to mitmproxy's flow list when mcp_view_sync_actions includes replay (default all). replay_request replays the original flow in-place when replay sync is enabled; otherwise it creates a detached replay flow.

Intercept tools (5)

Tool	Description
set_intercept_filter	Set filter expression (e.g. ~u example.com)
get_intercepted_flows	List currently intercepted flows
resume_flow	Resume a single intercepted flow
resume_all	Resume all intercepted flows
drop_flow	Drop an intercepted flow

Config tools (3)

Tool	Description
get_options	Get current mitmproxy options
set_option	Set a mitmproxy option (dangerous ones are blocked)
get_status	Get proxy status and version info

Options

Pass via --set flag or set in ~/.mitmproxy/config.yaml:

Option	Default	Description
mcp_transport	stdio	Transport: stdio, sse, or tcp
mcp_port	9011	Port for SSE/TCP transport
mcp_max_flows	1000	Max flows to keep in memory (oldest evicted first)
mcp_redact	false	Redact sensitive data (tokens, keys, passwords) before sending to AI
mcp_redact_patterns	(empty)	Additional redaction patterns as JSON array (requires mcp_redact: true)
mcp_view_sync_actions	all	Which MCP actions sync to mitmproxy view: all, none, replay, clear, or replay,clear

Example:

mitmdump -s addon.py --set mcp_transport=sse --set mcp_port=9011 --set mcp_max_flows=5000

Privacy

By default, redaction is off -- you see the raw traffic as-is. To enable it, set mcp_redact to true in your config or via flags:

# ~/.mitmproxy/config.yaml
mcp_redact: true

# or via flags
mitmdump -s addon.py --set mcp_redact=true

When enabled, the following are automatically redacted before reaching the AI:

• Bearer tokens, Basic auth credentials
• API keys (header and query parameter)
• Passwords, secrets
• JWTs
• Session IDs, auth tokens, session cookies

Request and response bodies are truncated to 10KB to prevent context overflow.

You can also add custom redaction patterns:

mitmdump -s addon.py --set mcp_redact=true --set mcp_redact_patterns='["internal_secret", "x-custom-key"]'

Project structure

mitmproxy-mcp/
  addon.py              thin wrapper for mitmproxy script loading
  mitmproxy_mcp/        main package
    __init__.py
    addon.py            mitmproxy addon with MCP server
    models.py           pydantic models for flow serialization
    storage.py          thread-safe in-memory flow storage
    privacy.py          redaction engine
    transport.py        stdio, sse, tcp transport layer
    tools/
      flows.py          flow query tools
      replay.py         replay and modification tools
      intercept.py      interception control tools
      config.py         proxy configuration tools
  tests/                test suite

Development

# install in editable mode (required for imports to work)
uv pip install -e ".[dev]"

# run tests
pytest tests/ -v

# run a specific test file
pytest tests/test_flow_tools.py -v

# with coverage
pytest tests/ --cov=mitmproxy_mcp --cov-report=html

# lint
ruff check .

# type check
mypy

License

MIT