# THIS PROJECT IS MADE BY LLM

# Tor Web MCP

Local MCP server for LM Studio with two tools:

- `tor_search(query, max_results=8)` — searches Ahmia's indexed onion services.
- `tor_fetch(url, max_chars=30000)` — fetches a v3 `.onion` URL through a local Tor SOCKS5 proxy.

## Install

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Set `TOR_SOCKS_URL` if your Tor SOCKS listener is not `127.0.0.1:9050`. Tor Browser commonly uses a different port, so verify your setup.

## Test

```bash
mcp dev server.py
```

## LM Studio

Configure a local stdio MCP server using absolute paths:

```json
{
  "mcpServers": {
    "tor-web": {
      "command": "/ABSOLUTE/PATH/tor-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/tor-mcp/server.py"]
    }
  }
}
```

## Error semantics

The fetcher deliberately returns LLM-readable error categories. In particular, a search result that is no longer reachable becomes:

`[SEARCH_RESULT_STALE]`

This means the URL was indexed but is currently unreachable; it does **not** prove the address is invalid. The model can then try another search result.

Other categories include `INVALID_ONION_URL`, `TOR_SEARCH_TIMEOUT`, `TOR_SEARCH_HTTP_ERROR`, `TOR_SEARCH_NETWORK_ERROR`, `NO_RESULTS`, `TOR_FETCH_NETWORK_ERROR`, `TOR_REDIRECT`, and `TOR_REDIRECT_BLOCKED`.

## Security boundaries

- Only HTTP/HTTPS v3 `.onion` URLs are accepted by `tor_fetch`.
- No automatic redirects outside `.onion`.
- Response size and network timeouts are bounded.
- No generic arbitrary proxy tool is exposed.
- Content returned by onion services must still be treated as untrusted web content.