Content
# Tool List
## Overview
tor_mcp — Tor connection MCP server (Dark Web OSINT support)
Access to .onion / Web via locally managed Tor process (SOCKS5h proxy).
**Passive OSINT information gathering** is the purpose.
```
Claude ──(MCP/stdio)──▶ tor_mcp ──(SOCKS5h)──▶ tor.exe ──▶ .onion / Web
└──(ControlPort/stem)──▶ tor.exe（circuit control）
```
## Provided Tools
### Tor Network
| Tool | Purpose |
|--------|------|
| `tor_check` | Verify if it's Tor and return exit node IP (10-40 seconds on first run) |
| `tor_fetch` | Retrieve .onion / Web pages (HTML → text formatting, title, link extraction) |
| `tor_new_circuit` | Request a new circuit (different exit IP). Returns changes in previous and current exit IPs |
| `onion_search` | Search .onion with Tor search engines (Tordex / Torch) |
### Browser (Playwright + Camoufox)
For pages requiring JavaScript rendering, login-required sites, or bulletin boards with queuing.
| Tool | Purpose |
|--------|------|
| `browser_open` | Open URL (automatic routing). Can be forced with `via` parameter |
| `browser_state` | Re-acquire current page state (for polling) |
| `browser_click` | Click element with CSS selector |
| `browser_fill` | Input value into field |
| `browser_wait` | Wait for selector appearance / URL change / text appearance |
| `browser_screenshot` | Save PNG screenshot |
| `browser_eval` | Execute JavaScript and retrieve result |
| `browser_login` | Read authentication information from environment variables and submit login form |
| `browser_close` | Close session (profile kept) |
| `browser_reset` | Close session and delete profile |
#### Browser Routing Design
```
Surface Web browser (Direct session)
↑ via="direct" or auto when clear net connection is successful
Dark Web browser (Tor session)
↑ via="tor" or .onion URL or auto for fallback
```
**Reasons for using two browser sessions:**
- Camoufox (Firefox) sets proxy at browser startup. Cannot switch between Tor and Direct within the same process.
- Surface Web and Dark Web are different investigation targets. It's better to keep cookies and session states separate to prevent contamination.
- Two windows may open, but this is intentional.
**`browser_open` `via` parameter:**
| Value | Behavior |
|----|------|
| `"auto"` (default) | .onion → Tor fixed. Clear net → Direct first, then try Tor if failed |
| `"tor"` | Always via Tor (even for clear net) |
| `"direct"` | Always Direct (reject .onion). Automatic restart if window is closed |
Check the actual route used in the `via` field of the result (`"direct"` / `"tor"` / `"tor_fallback"`).
#### Manual Testing (browse_cli.py)
```bash
# Start from OSINT root
uv run browse_cli.py
```
```
URL (Enter to quit): https://check.torproject.org/
Mode [a/t/d] (a): t
→ via=tor status=200 title='Tor Project | Are you using Tor?'
```
Mode specification: `a` = auto, `t` = force Tor, `d` = force Direct
## Setup
### 1. Dependency Packages
```bash
uv pip install -r tor_mcp/requirements.txt
```
(`mcp`, `httpx[socks]`, `stem`, `beautifulsoup4`)
### 2. Tor Binary (Tor Expert Bundle) Placement
Repository does not include binaries. Place them yourself (see [vendor/README.md](vendor/README.md)).
- Download: https://www.torproject.org/download/tor/ → **Windows Expert Bundle**
- Placement: Extracted `tor` folder contents into `tor_mcp/vendor/tor/` (so that `tor_mcp/vendor/tor/tor.exe` exists)
- Verification: `uv run python -m tor_mcp.tor_process --check-binary`
`tor.exe` path can be overridden with environment variable `TOR_MCP_TOR_EXE`.
### 3. Register as MCP Server
`tor-osint` server is defined in [.mcp.json](../.mcp.json). Start Claude Code in this directory to recognize it.
## Configuration (Environment Variables)
| Variable | Default | Description |
|------|------|------|
| `TOR_MCP_TOR_EXE` | `vendor/tor/tor.exe` | Tor binary path |
| `TOR_MCP_SOCKS_PORT` | `9050` | SOCKS5 port (beware of conflicts when using Tor Browser) |
| `TOR_MCP_CONTROL_PORT` | `9051` | ControlPort (for circuit control) |
Tor lifecycle is managed by the server (started on first tool usage, stopped on exit).
## Standalone Verification
```bash
# Detect Tor binary
uv run python -m tor_mcp.tor_process --check-binary
# Start Tor → bootstrap → stop
uv run python -m tor_mcp.tor_process --start
# Smoke test for all tools (with Tor communication, takes several tens of seconds)
PYTHONUTF8=1 uv run python -m tor_mcp.scratch
```
## Operation Tips / Troubleshooting
### Visual Confirmation with `manual_check.py` (piggyback on existing Tor)
Use `manual_check.py` to visually confirm results while MCP server is running. This script **does not start a new tor.exe, but piggybacks on the existing SOCKS 9050**, so there's no port conflict.
```bash
# Retrieve and display default 2 URLs (check.torproject + DuckDuckGo onion)
PYTHONUTF8=1 uv run python -m tor_mcp.manual_check
# Visually confirm arbitrary URL(s). Displays status / final URL / content-type / title / first 500 characters
PYTHONUTF8=1 uv run python -m tor_mcp.manual_check https://example.onion/
```
In contrast, `tor_process --start` and `scratch` **start their own tor.exe**, which conflicts with 9050/9051 if MCP server is already running. Use `manual_check.py` for visual confirmation.
### `Address already in use [WSAEADDRINUSE]` (startup failure)
9050/9051 is occupied by another tor.exe. Often due to leftover processes from previous runs.
```bash
netstat -ano | grep -E "9050|9051" # Identify occupying PID
taskkill //PID <PID> //F # Kill only those under vendor/tor
```
- **Tor Browser uses 9150/9151**, so it can coexist with this server (9050/9051). Do not kill Tor Browser's tor.exe. Identify it by `powershell -NoProfile -Command "Get-CimInstance Win32_Process -Filter \"name='tor.exe'\" | Select ProcessId,CommandLine | Format-List"`
and checking the CommandLine.
### Character Corruption (cp932)
When running on Japanese consoles, add `PYTHONUTF8=1` to prevent crashes and character corruption.
## Ethics and Legal Policy (Important)
- **Limit to passive information gathering** ( browsing and collecting public text).
- Do not use for unauthorized access, acquiring or trading illegal content, or active attacks.
- `onion_search` results may include unreviewed or illegal postings. **Results are subject to evaluator's judgment**, and the tool does not guarantee content legality.
- Conduct investigations within authorized scope, following laws and organizational regulations of each country.
## License / Copyright
Copyright (c) 2026 segfo
This software is released under the MIT License. See [LICENSE](LICENSE) for details.
