Skip to content
MCP server

torproxy

Tor proxy container with a REST API and a built-in MCP server for agents

Runs locallyStatus and history
Install
Pricing
Free
Platforms
CLI, self-hosted, Linux
Runs
Locally
Version
2.7.9
Listing updated
today

Similar MCP servers

About torproxy

torproxy is a free MCP server for security. It runs locally on your machine and is started by your AI client.

The MCP server is a feature of a larger Docker image: an HTTP proxy through Privoxy on port 8118, a SOCKS5 proxy on 9050 and a REST control API on 8080, all bound to 127.0.0.1 by default. The MCP server listens on port 2501 over SSE or runs over stdio with torproxy mcp, so Claude Desktop, Cursor and similar clients can manage Tor circuits and make anonymised web requests.

The README stresses fail-closed behaviour: if Tor drops, Privoxy returns 503 and a netfilter kill switch drops outgoing packets. A transparent gateway mode tunnels another container's TCP and DNS through Tor with no app changes. A reconnect call requests a new identity and can pick an exit country.

It lists use cases such as scraping with circuit rotation and fetching onion pages, and says it is not for streaming or voice, and that major CDNs often block known Tor exits. It warns that the proxy and API need no authentication, so they should not be exposed to untrusted networks.

Install

Run in a terminal

claude mcp add torproxy --env TORPROXY_API_TOKEN='<TORPROXY_API_TOKEN>' -- docker run -i --rm -e TORPROXY_API_TOKEN docker.io/hapheus/torproxy:2.7.9

Add to claude_desktop_config.json

{
  "mcpServers": {
    "torproxy": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TORPROXY_API_TOKEN",
        "docker.io/hapheus/torproxy:2.7.9"
      ],
      "env": {
        "TORPROXY_API_TOKEN": "<TORPROXY_API_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "torproxy": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TORPROXY_API_TOKEN",
        "docker.io/hapheus/torproxy:2.7.9"
      ],
      "env": {
        "TORPROXY_API_TOKEN": "<TORPROXY_API_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "torproxy": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TORPROXY_API_TOKEN",
        "docker.io/hapheus/torproxy:2.7.9"
      ],
      "env": {
        "TORPROXY_API_TOKEN": "<TORPROXY_API_TOKEN>"
      }
    }
  }
}

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

{
  "mcpServers": {
    "torproxy": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TORPROXY_API_TOKEN",
        "docker.io/hapheus/torproxy:2.7.9"
      ],
      "env": {
        "TORPROXY_API_TOKEN": "<TORPROXY_API_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "torproxy": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TORPROXY_API_TOKEN",
        "docker.io/hapheus/torproxy:2.7.9"
      ],
      "env": {
        "TORPROXY_API_TOKEN": "<TORPROXY_API_TOKEN>"
      }
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • TORPROXY_API_TOKENOptional secret token for authenticating REST and MCP requests.

What it does

HTTP and SOCKS5 proxy
Privoxy on 8118 and Tor SOCKS on 9050.
Kill switch
Fail-closed behaviour if Tor drops.
Gateway mode
Route other containers through Tor without app changes.
Circuit and country control
Request a new identity and choose an exit country.
Built-in MCP
SSE on port 2501 or stdio.

Good for

  • Give an agent anonymised web access
  • Fetch onion pages from an assistant
  • Rotate Tor circuits for scraping
  • Test country-specific content via exit nodes

Pricing

Free

Free; run with Docker

torproxy FAQ

Is it exposed publicly?

Ports bind to 127.0.0.1 by default.

Does it need authentication?

Proxies and API do not; an optional TORPROXY_API_TOKEN can protect REST and MCP requests.

Can it stream video?

The README says it is not designed for that.

How do I run it?

With docker compose up or docker run hapheus/torproxy.

Is torproxy free?

Yes. torproxy is free to use.

How do I add torproxy to Claude Code?

Run this command in your terminal: claude mcp add torproxy --env TORPROXY_API_TOKEN='<TORPROXY_API_TOKEN>' -- docker run -i --rm -e TORPROXY_API_TOKEN docker.io/hapheus/torproxy:2.7.9

What are the best alternatives to torproxy?

The closest alternatives to torproxy are REA, Scrapling MCP Server, Firecrawl MCP Server, Douyin_TikTok_Download_API and AiSOC.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers