# torproxy

> torproxy is a free MCP server for security. Tor proxy container with a REST API and a built-in MCP server for agents. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** CLI, self-hosted, Linux, macOS, Windows
- **Repository:** https://github.com/hapheus/torproxy
- **MCP Registry name:** io.github.hapheus/torproxy
- **Categories:** [security](https://ai-powered.com/categories/security), [web search and scraping](https://ai-powered.com/categories/web-search-and-scraping)
- **Listing updated:** 2026-11-18

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## 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.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Scrapling MCP Server](https://ai-powered.com/mcp/scrapling-mcp-server): Scrapling MCP Server is an open-source MCP server for web search and scraping.
- [Firecrawl MCP Server](https://ai-powered.com/mcp/firecrawl-mcp-server): Firecrawl MCP Server is a freemium MCP server for web search and scraping.
- [Douyin_TikTok_Download_API](https://ai-powered.com/mcp/douyin-tiktok-download-api): Douyin_TikTok_Download_API is an open-source MCP server for web search and scraping.
- [AiSOC](https://ai-powered.com/mcp/aisoc): AiSOC is an open-source MCP server for ai models and llm tooling.
- [SearXNG Search](https://ai-powered.com/mcp/searxng-search): SearXNG Search is an open-source MCP server for web search and scraping.
- [redamon](https://ai-powered.com/mcp/redamon): redamon is an open-source MCP server for ai models and llm tooling.
- [x64dbg-mcp-server](https://ai-powered.com/mcp/x64dbg-mcp-server): x64dbg-mcp-server is an open-source MCP server for ai models and llm tooling.

---
Source: https://ai-powered.com/mcp/torproxy
