OnionLens Tor Tools MCP server

OnionLens

A Python 3.10+ standard-library WSGI sensor for an application you own or are authorized to instrument. It stores observations locally in SQLite. There are no remote calls, downloads, hidden telemetry, background services or automatic Tor installation. The runtime has no third-party dependencies.

Since version 0.1.2 the distribution name is onionlens. The Python import remains onion_observatory. The onionlens, cepatreaza and onion-observatory commands invoke the same sensor. Existing integrations can keep their imports and command names.

PyPI · Website · Source repository

Install and run

python3 -m venv .venv
. .venv/bin/activate
pip install onionlens
onionlens serve --channel clearnet --db observatory.sqlite3

For a local source checkout, use python -m pip install . instead.

The reference server binds 127.0.0.1:8787 by default. Open http://127.0.0.1:8787/oo/demo for a labelled demonstration. The response contains a benign instruction to request a same-origin callback path. Following that path records a demo callback. /oo/probe issues an unsolicited-class probe instead. No application HTML is modified or injected.

onionlens summary --db observatory.sqlite3

Summary prints aggregate event counts, valid callbacks by class, and invalid callbacks. It prints no raw records. All activity outside the dedicated demo endpoint and its valid issued callback tokens is classified unsolicited. This operational label means unlabelled traffic, including your own ordinary tests. It does not establish that a visitor was uninvited. Spoofed user agents, test headers and query markers cannot suppress or relabel activity. The label says nothing about a visitor's identity.

Wrap your WSGI application

from onion_observatory import Sensor
from my_application import application as original_application

application = Sensor(original_application, "sensor.sqlite3",
                     channel="clearnet")

Choose a database file location outside your web root; :memory: is not supported. Create its parent directory first and restrict its permissions. The sensor reserves exactly /oo/probe, /oo/demo, and /oo/callback, relative to the application's mount point (SCRIPTNAME). The advertised callback path includes that mount point. Keep these paths outside your application's route space. All other response iterables and headers pass through unchanged, including encoded and streaming responses. Use a suitable production WSGI server for an exposed service. The Python reference server is for local demonstration, not hardened production hosting.

The channel is fixed operator configuration, never inferred from hosts, addresses or headers. To compare onion and clearnet traffic, run separate listeners with different fixed channels. They may share a database. Put your own authentication or access policy outside the sensor if these endpoints must be restricted.

Optional Tor exposure

Install and configure Tor yourself using its official documentation and your platform's supported package. An example torrc mapping for the loopback reference listener is:

HiddenServiceDir /var/lib/tor/onionlens/
HiddenServicePort 80 127.0.0.1:8787

Use a Tor-owned private directory appropriate to your installation, then run the listener with --channel onion. Tor provisions the onion hostname. This package does not manage Tor. A public exposure needs your own deployment, abuse handling, and threat assessment. Binding loopback prevents direct external access to the reference listener, but does not restrict Tor visitors once you expose it.

Validate and retrieve the owned fixture

Shortened. The full README is on GitHub.