OpenTor MCP

Quick start · Connect a client · Tools · Configuration · Security · Contributing

OpenTor MCP connects an MCP-compatible client to Playwright Firefox through a local Tor SOCKS5 proxy. It can browse HTTP(S) and .onion pages, return readable content and native screenshots, extract forum data, preserve sessions, and archive pages for offline review.

It is designed as a small, local-first side project for supervised research and experimentation.

Why OpenTor MCP

MCP-native

27 focused tools with native image results and safety annotations — screenshots and CAPTCHAs come back as real MCP image content, not base64 blobs in a text field.

Local-first

The browser, Tor connection, cookies, archives, and optional OCR all stay on your machine. Nothing is relayed through a third-party service.

Secure by default

JavaScript evaluation and invalid TLS certificates are off unless you explicitly opt in. Every request — including redirects — passes a URL policy gate.

Bounded responses

Pagination and output budgets keep a 4 MB page from flooding your client's context window.

Useful output

Page markdown, links, metadata, screenshots, forum threads, and posts — shaped for a model to read, not a human to squint at.

Session-aware

Cookies save to owner-only local files, archives capture HTML + text + metadata + screenshot, and circuits rotate on demand.

Related MCP server: ruyipage-mcp

How it works

%%{init: {'theme':'base','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif','themeVariables':{'primaryColor':'#7C3AED','primaryTextColor':'#FFFFFF','primaryBorderColor':'#6D28D9','lineColor':'#8B5CF6','edgeLabelBackground':'#4B5563','tertiaryTextColor':'#FFFFFF','fontSize':'15px'}}}%%
flowchart LR
    C["MCP client"] -->|stdio| S["OpenTor MCP<br/>27 tools"]
    S --> G{"URL policy<br/>gate"}
    G -->|allowed| F["Playwright<br/>Firefox"]
    F --> T["Tor SOCKS5<br/>127.0.0.1:9050"]
    T --> W["HTTP(S) sites<br/>.onion services"]

    classDef exit fill:#0891B2,stroke:#0E7490,color:#FFFFFF
    class W exit

Every stage before the exit — client, server, policy gate, browser, and Tor proxy — runs on your own machine. The server uses one shared browser context and serializes browser operations, so concurrent tool calls cannot race the active page.

Quick start

Requirements — macOS or Linux, Python 3.11+, and curl. The installer can install and start Tor with Homebrew, apt, or dnf; it may ask for sudo on Linux.

git clone https://github.com/Medamine-cheddadi/opentor-mcp.git
cd opentor-mcp
chmod +x install.sh
./install.sh

The installer creates .venv, installs Playwright Firefox, checks the Tor SOCKS port, and prints an MCP configuration using absolute paths. It uses the lockfile when uv is available and prints a warning before falling back to an unlocked pip install.

To include the heavier ddddocr dependency during installation, opt in explicitly:

TOR_MCP_INSTALL_OCR=true ./install.sh

Install uv and start Tor first, then run:

git clone https://github.com/Medamine-cheddadi/opentor-mcp.git
cd opentor-mcp
uv sync --locked
uv run playwright install firefox              # macOS
uv run playwright install --with-deps firefox  # Linux; may install system packages

Optional local CAPTCHA OCR is deliberately separate from the core installation:

uv sync --locked --extra ocr          # ddddocr

# Tesseract requires both the system executable and Python bindings:
brew install tesseract                # macOS
sudo apt install tesseract-ocr        # Debian/Ubuntu
uv sync --locked --extra tesseract

Connect an MCP client

Use an absolute path to the virtual environment created inside the repository.

Claude Code

claude mcp add \
  --scope user \
  --env TOR_SOCKS_PORT=9050 \
  --env TOR_CONTROL_PORT=9051 \
  --env TOR_MCP_DIR=/absolute/path/opentor-mcp \
  --env TOR_ALLOW_JAVASCRIPT=false \
  --env TOR_IGNORE_HTTPS_ERRORS=false \
  --transport stdio opentor-mcp -- \
  /absolute/path/opentor-mcp/.venv/bin/tor-mcp

claude mcp list

The example uses user scope so the server is available across your Claude Code projects. For a narrower setup, use --scope local and run the command from each project that should access it. See the Claude Code MCP documentation for scope and configuration options.

Generic stdio configuration

Other clients use different configuration files and formats. For clients that accept the common JSON mcpServers shape:

{
  "mcpServers": {
    "opentor-mcp": {
      "command": "/absolute/path/opentor-mcp/.venv/bin/tor-mcp",
      "env": {
        "TOR_SOCKS_PORT": "9050",
        "TOR_CONTROL_PORT": "9051",
        "TOR_HEADLESS": "true",
        "TOR_MCP_DIR": "/absolute/path/opentor-mcp",
        "TOR_ALLOW_JAVASCRIPT": "false",
        "TOR_IGNORE_HTTPS_ERRORS": "false"
      }
    }
  }
}

First prompts

Restart your MCP client after adding the server, then try:

Check whether my browser traffic is using Tor.
Open the DuckDuckGo onion service and search for Tor Project documentation.
Read the current page and return a short summary with its links.
Take a screenshot of the current viewport.

Screenshot and CAPTCHA workflows require a client that can render native MCP image content.

Tools

Navigation

Reading

Interaction

Search and extraction

CAPTCHA assistance

Sessions

Tor control and archiving

CAPTCHA assistance

The primary flow returns a CAPTCHA as native MCP image content so a vision-capable client can read it. If installed, ddddocr or Tesseract can provide a local hint and optionally fill the answer. OCR is best-effort, and the image is preserved when OCR fails.

Sessions and archives

Saved sessions contain authentication cookies and must be treated as credentials. Session names use the strict pattern ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$; directories are created with mode 0700 and files with mode 0600 on supported systems.

tor_save_session(name="research-forum")
tor_load_session(name="research-forum")

Archives contain raw HTML, text, metadata, and a screenshot. They remain untrusted even when opened offline. Session and archive directories are ignored by Git.

Configuration

Circuit rotation requires an authenticated Tor control port. A minimal cookie-authentication setup in torrc is:

ControlPort 9051
CookieAuthentication 1

Restart Tor after changing its configuration. Browsing still works when the control port is unavailable, but tor_new_identity cannot request a new circuit.

Security model

• Every browser HTTP(S) request is checked against the URL policy, including redirects and page-initiated requests.

• Direct navigation accepts only absolute HTTP(S) URLs, so navigation to local files is rejected.

• The HTTP(S) request gate rejects embedded credentials, localhost, non-ASCII host aliases, and private, loopback, reserved, or link-local IP destinations.

• Page-derived text is labeled as untrusted, and JSON responses use an { "untrusted": true, "data": ... } envelope.

• TOR_ALLOW_JAVASCRIPT gates the arbitrary tor_evaluate_js tool only; JavaScript belonging to visited websites remains enabled in Firefox.

• Invalid TLS certificates require explicit opt-in.

• Screenshot, text, field, and item budgets constrain MCP response size.

• Browser operations are serialized, and Playwright resources are closed with the MCP lifecycle.

Please report vulnerabilities privately as described in SECURITY.md.

Limitations

• OpenTor MCP uses stock Playwright Firefox through Tor. It is not Tor Browser and does not provide Tor Browser's fingerprinting defenses or anonymity guarantees.

• The server owns one shared browser context. It is intended for one trusted local operator, not as a multi-user hosted service.

• Forum extraction is heuristic, and site layouts can change without notice.

• Onion services and bundled search providers may be unavailable or change addresses.

• To preserve Tor's remote DNS behavior, OpenTor MCP does not resolve public hostnames locally before navigation. The request gate rejects literal and browser-normalized local IP forms, not a public hostname based on its future DNS answer.

• The automated test suite uses fakes; live Tor connectivity remains an explicit local smoke test.

Development

uv sync --locked --extra dev
uv run ruff format --check src tests
uv run ruff check .
uv run pyright src
uv run pytest --cov=tor_mcp --cov-report=term-missing
uv run python -m build
uv run pip-audit

The test suite must remain network-free and maintain at least 80% branch coverage. See CONTRIBUTING.md for the workflow and pull-request checklist.

Responsible use

Use this project only for lawful, authorized research, testing, privacy work, or personal browsing. You are responsible for complying with applicable laws, service terms, and data-handling rules. Do not use it to access accounts or systems without permission, evade controls, or cause harm.

License

Released under the MIT License.