torproxy — Claude Code MCP server: features and setup
This MCP server for Claude Code connects an AI agent to a Tor proxy. The agent can route requests through Tor and select an exit country.
MIT ★ 7 updated 2026-11-13
claude mcp add --env TORPROXY_API_TOKEN=<TORPROXY_API_TOKEN> --transport stdio torproxy -- docker run -i --rm -e TORPROXY_API_TOKEN docker.io/hapheus/torproxy:2.7.7What torproxy does
torproxy combines Tor HTTP and SOCKS5 proxies with a REST API and an MCP server. Agents connect through MCP; the REST API can request a new Tor circuit and set the exit-node country.
Setup requires Docker and a value for TORPROXY_API_TOKEN. The command starts docker.io/hapheus/torproxy:2.7.7 as a stdio container. Proxy and API ports bind to 127.0.0.1 by default, but they do not require authentication, so they should not be exposed to untrusted networks.
What it helps with
- route an agent's requests through Tor
- switch the Tor exit country when reconnecting
- check a localized site through an exit node in another country
- send a container's traffic through Tor without changing application code
Example prompts for the agent
- Send a request to this site through Tor.
- Reconnect Tor using a German exit node.
- Check how this site appears through Tor from another country.
How to install torproxy
Platform CLI
claude mcp add --env TORPROXY_API_TOKEN=<TORPROXY_API_TOKEN> --transport stdio torproxy -- docker run -i --rm -e TORPROXY_API_TOKEN docker.io/hapheus/torproxy:2.7.7Replace <…> with your own values
Platform CLI
codex mcp add torproxy --env TORPROXY_API_TOKEN=<TORPROXY_API_TOKEN> -- docker run -i --rm -e TORPROXY_API_TOKEN docker.io/hapheus/torproxy:2.7.7Replace <…> with your own values
Config file
{
"mcpServers": {
"torproxy": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"TORPROXY_API_TOKEN",
"docker.io/hapheus/torproxy:2.7.7"
],
"env": {
"TORPROXY_API_TOKEN": "<TORPROXY_API_TOKEN>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"torproxy": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"TORPROXY_API_TOKEN",
"docker.io/hapheus/torproxy:2.7.7"
],
"env": {
"TORPROXY_API_TOKEN": "<TORPROXY_API_TOKEN>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e TORPROXY_API_TOKEN=<TORPROXY_API_TOKEN> torproxy docker run -i --rm -e TORPROXY_API_TOKEN docker.io/hapheus/torproxy:2.7.7Replace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about torproxy
How do I install torproxy in Claude Code?
Set TORPROXY_API_TOKEN, then run `claude mcp add --env TORPROXY_API_TOKEN=<TORPROXY_API_TOKEN> --transport stdio torproxy -- docker run -i --rm -e TORPROXY_API_TOKEN docker.io/hapheus/torproxy:2.7.7`. Docker is required to start the container.
What does torproxy do?
It provides HTTP and SOCKS5 access to Tor, a REST API for connection control, and an MCP server for AI agents. The API can request a new Tor circuit and choose its exit country.
What does torproxy require?
The MCP setup needs Docker and a value for TORPROXY_API_TOKEN. The container uses docker.io/hapheus/torproxy:2.7.7.