Onion Search

darkweb-mcp (onion-search-mcp)

用于搜索洋葱服务并通过 Tor 阅读页面的本地 Python stdio MCP 服务。它提供 5 个工具、8 个搜索适配器、内存缓存和 2 个 MCP 资源。

重要

隐私： 对敏感搜索使用本地模型。云端模型可能会通过 MCP 客户端接收你的查询和获取的内容。请检查客户端的日志记录、遥测和云端回退设置。

警告

用户责任： 你需要对自己的行为及其是否符合适用法律负责。在法律允许的范围内，作者和贡献者不对使用或滥用本软件承担责任。

运行

双容器配置会为 MCP 进程提供内部 Docker 网络。只有 Tor 容器具有外部路由。

docker compose build
docker compose up -d tor
docker compose run --rm --no-deps -T server

等待 docker compose ps 显示 Tor 状态为 healthy 后，再启动服务。服务通过 stdin 和 stdout 传输 MCP 消息。请让 stdout 保持连接到客户端。 如需使用包含 Tor 的单容器：

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

捆绑的容器具有外部路由，因为 Tor 需要该路由。请使用 Compose 隔离服务与 Tor 之间的网络。Tor 初次引导可能需要几分钟。 如需在 Linux 上本地安装 Python，请安装 Tor 和 libseccomp2，然后：

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

如需使用现有的 Tor 进程，请配置 SocksPort 9050 IsolateSOCKSAuth、ControlPort 9051 和控制认证，然后运行 uv run onion-search-mcp。如有需要，请设置 TOR_CONTROL_PASSWORD 或 TOR_COOKIE_FILE。

内容过滤开关

默认启用过滤。可通过环境配置或 CLI 选项，为进程关闭或开启过滤：

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

每个内容工具也接受 content_filter。传入 false 可在本次调用中禁用过滤，传入 true 可启用过滤，省略该参数则使用进程设置。

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

此开关控制域名屏蔽列表和关键词规则。Tor 路由、URL 验证、纯文本获取、解析器限制和不可信内容包装始终生效。搜索引擎可能会应用自身的过滤。缓存条目按过滤设置分开存储。

MCP 客户端配置

使用 docker compose up -d tor 启动 Tor 伴随容器，然后配置 stdio 客户端：

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

对于捆绑的镜像，将 docker run -i --rm onion-search-mcp:local 用作命令和参数。对于 Python，请使用 uv --directory /absolute/path/to/onion run --frozen onion-search-mcp。工具审批在客户端中配置。

工具

工具	参数	输出
onion_search	query, engines, limit=20, page=1, content_filter	排序后的结果、一致性、来源记录、失败的引擎
onion_fetch	url, max_chars=20000, include_links=true, content_filter	Markdown 文本、标题、链接、响应元数据
onion_status	url, timeout_s=30, content_filter	可访问性、HTTP 状态、延迟、错误代码
onion_links	url, onion_only=true, content_filter	Onion 链接和可选的明网链接，不会跟踪这些链接
tor_health	无	SOCKS 握手、引导百分比、Tor 版本
onion://engines 列出已启用的适配器、地址、验证状态和最近观测到的运行状况。onion://history 包含此进程中最近的 100 条查询。两者都是内存资源。
来源包括引擎、URL、UTC 抓取时间，以及 Tor 报告的电路 ID。缺少电路 ID 时，其值为 null。缓存的来源保留原始抓取时间。up=true 表示收到了 HTTP 响应，包括 4xx 和 5xx 响应。exit_check=false 表示未执行明网出口检查；Onion 服务不使用出口中继。
搜索查询会先去除首尾空白，长度上限为 256 个字符。结果数限制为 1 至 50，页数为 1 至 10000，抓取文本长度为 1 至 200000 个字符，状态超时为 1 至 120 秒。仅接受主机名为 56 个字符的 base32 Onion 主机的 HTTP(S) URL。凭据、v2 主机、IP 主机、其他协议以及明网重定向均会被拒绝。
非文本响应会返回元数据和 UNSUPPORTED_CONTENT，且不会读取响应正文。被拦截的抓取请求会返回 blocked=true 和空内容。被拦截的结果和出站链接会被省略。必需关键词匹配会屏蔽整个页面。返回文本中已知的被拦截域名会被编辑处理。

配置

变量	默认值	用途
TOR_SOCKS	127.0.0.1:9050	数字格式的代理 IP 和端口；不使用本地 DNS
TOR_CONTROL	127.0.0.1:9051	数字格式的控制 IP 和端口
TOR_CONTROL_PASSWORD	未设置	控制密码；Compose 提供本地默认值
TOR_COOKIE_FILE	未设置	SAFECOOKIE 身份验证文件
TOR_BRIDGES	空	以换行符或分号分隔的网桥行
ENGINES	all	以逗号分隔的已配置引擎标识符
ENGINES_FILE	engines.yaml	引擎配置，带有打包的备用配置
BLOCKLIST_PATHS	blocklists/csam.txt	以逗号分隔的纯域名或 MD5 阻止列表
CONTENT_FILTER	true	所有内容工具的默认设置
TERMS_FILE	blocklists/terms.txt	必需的术语列表，带有打包的备用文件
KEYWORD_FILTER	false	启用额外的关键词规则
FILTER_KEYWORDS	空	额外的逗号分隔字面术语
MAX_FETCH_BYTES	5242880	原始响应和解压后响应的字节数限制
CACHE_TTL_S	900	搜索 TTL；设为 0 时会禁用两个缓存
FETCH_CACHE_TTL_S	600	获取 TTL
CACHE_MAX_ENTRIES	128	每个缓存的最大条目数
CACHE_MAX_BYTES	33554432	每个缓存的最大序列化字节数
ENGINE_RATE_LIMIT_S	3	每个引擎的最小间隔
JITTER_S	2	扇出请求的最大随机延迟
ENGINE_TIMEOUT_S	25	每个引擎的截止时间
SEARCH_TIMEOUT_S	40	整个扇出请求的截止时间
REQUEST_TIMEOUT_S	40	请求总截止时间
LOG_QUERIES	false	不接受 true；不保存磁盘历史记录
八个适配器均已启用：ahmia、torch、haystak、onionland、tor66、excavator、deep_search、onion_search_engine。地址和请求参数存放在 YAML 中。要更改容器默认值，请编辑该文件并重新构建镜像；不会挂载主机目录。
使用前，请对照各运营方公布的地址核实当前地址。--verify-engines 会通过 Tor 检查可访问性，但无法确认运营方身份。有关证据和当前限制，请参阅引擎验证。
阻止列表是一个快照，不会自动下载或检查更新。其来源和刷新流程请参阅阻止列表来源。
通过 TOR_BRIDGES 在 Tor 容器中配置网桥。容器内包含 obfs4 和 Snowflake 可执行文件。请从可信来源获取当前网桥行，然后重新创建 sidecar。

隐私与限制

所有 HTTP 请求都通过 SOCKS 使用远程 DNS，凭据根据随机进程会话和每个目标生成。Tor 必须使用 IsolateSOCKSAuth。SOCKS 凭据会隔离数据流，但不能保证每个请求都使用新的物理线路。关闭时会请求 NEWNYM；Tor 可能会对该信号实施速率限制。 HTTP 客户端不存储 Cookie，也不会发送 Referer。它只执行 GET 请求，不会执行 JavaScript、提交表单、自动跟踪链接、渲染图像或解码媒体。响应会以流式方式读取，并设有字节数限制、读取截止时间和总截止时间。发出请求前会验证重定向目标。 HTML 解析在独立的 Linux 进程中运行，地址空间限制为 384 MiB、CPU 时间限制为 8 秒、截止时间为 10 秒，并通过 seccomp 规则禁止网络系统调用。脚本、样式、注释、嵌入对象和隐藏元素都会被移除。不可信文本会用新生成的分隔符括起来。这些措施不能证明页面不包含提示词注入，也不能证明链接可信。 查询历史记录和缓存仅保存在内存中，并会在关闭时清除。此项目未实现遥测、查询日志、磁盘缓存或运行时更新检查。MCP 客户端和模型运行时有各自的存储与网络行为；请参阅上文的隐私声明。 阻止列表和字面关键词无法检测所有有害内容。链接仅供研究参考；引擎间的结果一致性是一种排名信号。

开发

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

单元测试套件使用已保存的解析器测试样例和本地 SOCKS 模拟器。泄漏测试会停止代理，并断言连接仅指向本地代理，不会进行目标 DNS 查询或建立直接 HTTP 连接。CI 会在私有本地 Tor 网络上运行集成测试。测试会发布一个仅包含测试样例的临时 onion 服务。它绝不会查询公共搜索引擎，也不会读取第三方 onion 页面。

uv run python tests/integration/run.py

可以通过 TEST_TOR_SOCKS 和 TEST_TOR_CONTROL 指定现有的 Tor 实例。集成测试需要可用的 Tor 电路，网络不可用时可能会失败。请参阅测试。 稳定错误包括 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 和 PARSE_TIMEOUT。工具错误包含经过清理的代码和消息 JSON。部分搜索会包含各引擎的错误代码，并返回已完成的结果。

许可证

MIT。请参阅 LICENSE。