HTTrack MCP Server

HTTrack MCP 服务

一个 FastMCP（Model Context Protocol）服务，封装了经典的 HTTrack 网站复制工具，让 AI Agent 能通过 MCP 将网站镜像到 共享存档中，然后浏览、阅读和搜索下载的内容。

版权所有 (C) 2026 Tech Ventures VCC。 根据 GNU Affero General Public License v3.0 授权（参见 LICENSE）。

为什么需要它

HTTrack 是经过实战检验的离线网站复制工具，但它没有脚本 API，只有 GUI 和 CLI。本服务让它原生适用于 Agent：大模型 Agent 可以调用 mirror_site 在后台开始下载，轮询 mirror_status，之后通过 catalog、list_files、read_file 和 search_files 基于存档回答问题。

工具

工具	用途
mirror_site(url, project, depth, max_rate, filters)	在存档中启动后台镜像（/data/<project>）。每个项目只能有一个活动镜像任务；同一项目的并发请求会返回 already_running 和当前的 job_id；不同项目可以并行运行。
mirror_status(job_id)	任务状态（running / done / failed + 日志尾部）。省略参数可列出近期任务；也接受项目名称。
catalog()	所有项目：简称、简短描述（根据各网站的 <title>/meta description 自动生成）、源 URL、状态、页面/文件数量、大小。
list_files(project, subpath)	列出项目内的目录（名称、类型、大小、修改时间）。
read_file(project, path, max_bytes)	读取一个文本文件（HTML/JS/CSS/txt/json/md）。拒绝二进制文件；内容上限为 256 KB，以控制 Agent 上下文大小。
search_files(project, query, max_results)	在项目的文本文件中进行不区分大小写的子字符串搜索，并限制结果数量。

快速开始

先决条件：Docker。

docker build -t httrack-mcp-server .

docker run -d --name httrack-mcp --restart unless-stopped \
  -p 9050:8000 \
  -v /path/to/your/archive:/data:rw \
  httrack-mcp

容器通过 http://<host>:9050/mcp 上的可流式 HTTP 暴露 MCP 服务。

在 MCP 客户端中注册

MCPHub 风格网关（streamable-http）示例：

{
  "httrack": {
    "type": "streamable-http",
    "url": "http://192.168.1.35:9050/mcp",
    "enabled": true,
    "description": "HTTrack site mirroring + archive browsing",
    "owner": "admin"
  }
}

支持可流式 HTTP 的客户端无需额外身份验证即可连接到 /mcp （不会验证任何人的身份；请在可信网络上运行，或将其置于网关身份验证之后）。完整用法、示例和故障排除，请参阅 HELP.md。

并发模型

• 每个项目运行一个 httrack 进程，并通过各自的输出目录隔离——项目之间不共享 状态，因此多个 Agent 可以并行镜像不同网站。
• mirror_site 会阻止对同一项目重复镜像（进程内任务表 + 对写入该项目目录的 httrack 进程进行 /proc 扫描）。

CI

GitHub Actions 会在每次 PR 和推送时运行：检查 server.py 的 Python 语法、 验证 Dockerfile 基本断言，并构建 Docker 镜像。

许可证

本程序是自由软件：你可以根据自由软件基金会发布的 GNU Affero General Public License 条款重新分发和／或修改本程序，可以选择使用该许可证的第 3 版，或（由你选择）任何更新版本。

如果你将此服务的修改版作为网络服务运行，AGPL §13 要求你向用户提供该修改版的对应源代码。

版权所有 (C) 2026 Tech Ventures VCC。HTTrack 本身由 Xavier Roche 和 贡献者根据 GPL 授权；本项目仅通过 shell 调用它，与其无关联。