spignelon/ddg-onion-mcp

An MCP server that gives an AI client web search and page
reading, entirely over Tor: search goes through DuckDuckGo's Lite onion service, and pages
are fetched and reduced to clean Markdown. There is no direct-connection fallback. Single Go
binary, no external accounts or API keys.
Lightweight: Docker image is ~12 MB, container idles at ~20 MB RAM.
> Same job as nickclyde/duckduckgo-mcp-server and the Brave Search MCP server, for people who
> want the traffic to leave through Tor and the server to be tiny.
## ⚠️ Read before you deploy this
Search queries are not private from your model provider. Tor hides your IP from DuckDuckGo
and from the sites you fetch. The AI service that writes the queries (OpenRouter, OpenAI, ...)
still sees them.
Tor does not make this indistinguishable from Tor Browser. Only the HTTP request headers are
matched. The TLS and HTTP/2 fingerprints are still Go's, so a site that compares them can tell
(see Request identity).
Fetched pages are untrusted input. A page can contain text that tries to instruct your
model. Both tools are marked read-only and say so, but treat the output accordingly.
No bot-detection bypass. If DuckDuckGo or a site refuses or challenges the client, the server
reports an error. It does not retry under another identity and does not solve challenges.
Respect the terms of the sites you query.
## Quick start (Docker)
The image does not contain Tor. It needs a Tor service running on the host OS, and uses its
SOCKS proxy at 127.0.0.1:9050 (the default of the distribution packages). Install and start it
first:
| Distribution | Install and start |
| Debian / Ubuntu | sudo apt install tor && sudo systemctl enable --now tor |
| Arch | sudo pacman -S tor && sudo systemctl enable --now tor |
| Fedora | sudo dnf install tor && sudo systemctl enable --now tor |
| openSUSE | sudo zypper install tor && sudo systemctl enable --now tor |
Then check that it is listening: ss -tln | grep 9050 should show 127.0.0.1:9050. (The tor
service name and port were confirmed on openSUSE Tumbleweed; the other rows are the standard
package names and have not been run by the author.) Without this service the container refuses to
start, see "No Tor, no fallback" below.
Inside a normal container 127.0.0.1 is the container itself, so run it with --network host.
No repo clone needed:
bash
export DDG_MCP_AUTH_TOKEN=$(openssl rand -hex 24)
echo "$DDG_MCP_AUTH_TOKEN" # keep this: your MCP client needs it as a bearer token
docker run -d --name ddg-onion-mcp --restart unless-stopped \
--network host \
-e DDG_MCP_AUTH_TOKEN \
ghcr.io/spignelon/ddg-onion-mcp:latest
Alternative: clone the repo and use compose.yaml (hardened: read-only filesystem, all
capabilities dropped, 128 MB memory cap):
bash
git clone https://github.com/spignelon/ddg-onion-mcp.git && cd ddg-onion-mcp
export DDG_MCP_AUTH_TOKEN=$(openssl rand -hex 24)
docker compose up -d
The MCP endpoint is http://127.0.0.1:8085/mcp with the header Authorization: Bearer .
With host networking nothing is published with -p: the server listens directly on the host's
loopback (change it with -e DDG_MCP_LISTEN=host:port).
Desktop MCP clients (stdio): have the client run the image itself: