Onion Search

darkweb-mcp (onion-search-mcp)

A local Python stdio MCP server for searching onion services and reading pages through Tor. It provides five tools, eight search adapters, memory caches, and two MCP resources.

[!IMPORTANT] Privacy: Use a local model for sensitive searches. Cloud models may receive your queries and fetched content through the MCP client. Check the client's logging, telemetry, and cloud fallback settings.

[!WARNING] User responsibility: You are responsible for your actions and compliance with applicable laws. The authors and contributors disclaim liability for use or misuse of this software to the extent permitted by law.

Run

The two-container setup gives the MCP process an internal Docker network. Only the Tor container has an external route.

docker compose builddocker compose up -d tordocker compose run --rm --no-deps -T server

Wait for docker compose ps to show Tor as healthy before starting the server. The server uses stdin and stdout for MCP messages. Keep stdout attached to the client. For a single container with Tor included:

docker run -i --rm --read-only --cap-drop ALL --security-opt no-new-privileges:true --tmpfs /tmp:rw,noexec,nosuid,size=96m,uid=10001,gid=10001,mode=1770 --memory 768m --cpus 2 onion-search-mcp:local

The bundled container has an external route because Tor needs one. Use Compose for network isolation between the server and Tor. Initial Tor bootstrap can take several minutes. For a local Python installation on Linux, install Tor and libseccomp2, then:

uv sync --frozenuv run onion-search-mcp --bundled-tor

To use an existing Tor process, configure SocksPort 9050 IsolateSOCKSAuth, ControlPort 9051, and control authentication, then run uv run onion-search-mcp. Set TOR_CONTROL_PASSWORD or TOR_COOKIE_FILE if needed.

Content filtering switch

Filtering is enabled by default. Turn it off or on for the process with either environment configuration or CLI options:

CONTENT_FILTER=false uv run onion-search-mcpuv run onion-search-mcp --no-content-filteruv run onion-search-mcp --content-filterCONTENT_FILTER=false docker compose run --rm --no-deps -T server

Each content tool also accepts content_filter. Pass false to disable filtering for that call, true to enable it, or omit it to use the process setting.

{"name":"onion_fetch","arguments":{"url":"http://YOUR_56_CHARACTER_ADDRESS.onion/","content_filter":false}}

The switch controls domain blocklists and keyword rules. Tor routing, URL validation, text-only retrieval, parser limits, and untrusted-content wrapping always apply. Search engines may apply their own filtering. Cache entries are separated by filter setting.

MCP client configuration

Start the Tor sidecar with docker compose up -d tor, then configure a stdio client:

{  "mcpServers": {    "onion-search": {      "command": "docker",      "args": ["compose", "--project-directory", "/absolute/path/to/onion", "run", "--rm", "--no-deps", "-T", "server"]    }  }}

For the bundled image, use docker run -i --rm onion-search-mcp:local as the command and arguments. For Python, use uv --directory /absolute/path/to/onion run --frozen onion-search-mcp. Tool approval is configured in the client.

Tools

Configuration

Privacy and limits

All HTTP requests use remote DNS through SOCKS, with credentials derived from a random process session and each destination. Tor must use IsolateSOCKSAuth. A SOCKS credential separates streams but does not guarantee a new physical circuit for every request. NEWNYM is requested at shutdown; Tor may rate limit that signal. The HTTP client stores no cookies and sends no Referer. It performs GET requests only. It does not execute JavaScript, submit forms, follow links automatically, render images, or decode media. Responses are streamed with byte limits and read and total deadlines. Redirect targets are validated before a request is made. HTML parsing runs in a separate Linux process with a 384 MiB address-space limit, 8 seconds of CPU, a 10-second deadline, and seccomp rules that deny network syscalls. Scripts, styles, comments, embedded objects, and hidden elements are removed. Untrusted text is wrapped with a fresh delimiter. These measures do not prove that a page contains no prompt injection or that a link is legitimate. Query history and caches stay in memory and are cleared on shutdown. No telemetry, query logging, disk cache, or runtime update checks are implemented. The MCP client and model runtime have their own storage and network behavior; see the privacy notice above. Blocklists and literal keywords do not detect all abusive content. Links are research leads; engine agreement is a ranking signal.

Development

uv sync --frozenuv run ruff check .uv run pytest -q -m 'not integration'docker compose config --quietuv build

The unit suite uses saved parser fixtures and a local SOCKS simulator. The leak test stops the proxy and asserts that connections target only the local proxy, with no destination DNS or direct HTTP connection. CI runs integration on a private local Tor network. The test publishes a temporary onion service containing only fixtures. It never queries public search engines or reads third-party onion pages.

uv run python tests/integration/run.py

An existing test Tor instance can be supplied with TEST_TOR_SOCKS and TEST_TOR_CONTROL. Integration requires a usable Tor circuit and can fail when the network is unavailable. See testing. Stable errors include TOR_UNAVAILABLE, INVALID_ONION, BLOCKED, TIMEOUT, ALL_ENGINES_FAILED, UNSUPPORTED_CONTENT, INVALID_QUERY, INVALID_ENGINE, INVALID_INPUT, CONFIG_ERROR, RESPONSE_TOO_LARGE, REDIRECT_LIMIT, PARSE_FAILED, and PARSE_TIMEOUT. Tool errors contain scrubbed code and message JSON. Partial searches include per-engine codes and return completed results.

License

MIT. See LICENSE.