caido-mcp-server

MCP server and CLI for Caido web proxy - browse, replay, and analyze HTTP traffic from AI assistants or your terminal.

What It Does

Two ways to interact with your Caido proxy:

• MCP Server - expose Caido tools to AI assistants (Claude Code, Cursor, etc.) via the Model Context Protocol
• CLI - standalone terminal client for pentesters who prefer the command line

Both share the same auth token, the same Go SDK, and the same codebase.

Features

Built-in optimizations:

• Token auto-refresh - expired tokens refresh mid-session automatically
• Session reuse - single replay session per server lifetime, no sprawl
• Body limits - response bodies capped at 2KB by default to save LLM context
• Minimal tool descriptions - optimized for low token overhead per API call

MCP Server

Install

curl -fsSL https://raw.githubusercontent.com/c0tton-fluff/caido-mcp-server/main/install.sh | bash

Or download a pre-built binary from Releases (macOS, Linux, Windows - amd64/arm64).

git clone https://github.com/c0tton-fluff/caido-mcp-server.git
cd caido-mcp-server
go build -ldflags "-X main.version=$(git describe --tags)" -o caido-mcp-server ./cmd/mcp

Quick Start

1. Authenticate

CAIDO_URL=http://localhost:8080 caido-mcp-server login

This opens your browser for OAuth device-flow authentication and saves the token to ~/.caido-mcp/token.json.

2. Configure your MCP client

Add to ~/.mcp.json (Claude Code) or your editor's MCP config:

{
  "mcpServers": {
    "caido": {
      "command": "caido-mcp-server",
      "args": ["serve"],
      "env": {
        "CAIDO_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

3. Use it

"List all POST requests to /api"
"Send this request with a modified user ID"
"Create a finding for this IDOR"
"Show fuzzing results from Automate session 1"
"What's in scope?"

MCP Tools (20)

caido_list_requests

caido_get_request

caido_send_request

caido_get_replay_entry

caido_get_automate_entry

caido_create_finding

caido_create_scope

caido_select_project

caido_intercept_control

CLI

Standalone terminal client for Caido. No MCP required - use it directly from your shell.

Install

curl -fsSL https://raw.githubusercontent.com/c0tton-fluff/caido-mcp-server/main/install.sh | TOOL=cli bash

Or download from Releases.

git clone https://github.com/c0tton-fluff/caido-mcp-server.git
cd caido-mcp-server
go build -o caido-cli ./cmd/cli

Usage

Requires the same auth token as the MCP server - run caido-mcp-server login first.

# Check connection and auth
caido status -u http://localhost:8080

# Send structured requests
caido send GET https://target.com/api/users
caido send POST https://target.com/api/login -j '{"user":"admin","pass":"test"}'
caido send PUT https://target.com/api/profile -H "Authorization: Bearer tok" -j '{"role":"admin"}'

# Send raw HTTP requests
caido raw 'GET /api/users HTTP/1.1\r\nHost: target.com\r\n\r\n'
caido raw -f request.txt --host target.com --port 8443
echo -n 'GET / HTTP/1.1\r\nHost: example.com\r\n\r\n' | caido raw -

# Browse proxy history
caido history
caido history -f 'req.host.eq:"target.com"' -n 20

# Get full request/response details
caido request 12345

# Encode/decode
caido encode base64 "hello world"
caido decode url "%3Cscript%3E"
caido encode hex "test"

Commands

Global Flags

Architecture

caido-mcp-server/
  cmd/
    mcp/          MCP server (stdio transport)
    cli/          Standalone CLI
  internal/
    auth/         OAuth device flow, token store, auto-refresh
    httputil/     HTTP parsing, CRLF normalization, URL handling
    replay/       Replay session management, response polling
    tools/        MCP tool definitions (one file per tool)

Both cmd/mcp and cmd/cli share internal/ packages. The project uses caido-community/sdk-go for all GraphQL communication with Caido.

Troubleshooting

MCP server logs: ~/.cache/claude-cli-nodejs/*/mcp-logs-caido/

Contributing

1. Fork the repo
2. Create a feature branch
3. go build ./... and go test ./...
4. Open a PR

Built with caido-community/sdk-go and modelcontextprotocol/go-sdk.

License

MIT