Mitmproxy Mcp

mitmproxy-mcp

[](https://github.com/moha-abdi/mitmproxy-mcp/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT)

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.

OpenCode

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
    }
  }
}

Claude Code

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"
    }
  }
}

Cursor

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

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

Windsurf

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

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

VS Code (Copilot)

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

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

Claude Desktop

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"]
    }
  }
}

Other clients

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

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: moha-abdi
• Source: moha-abdi/mitmproxy-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.