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.

Related MCP server: mitm-mcp

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

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

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

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

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

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

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

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

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

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)

Replay tools (4)

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)

Config tools (3)

Options

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

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