Gopeed 如何启用 MCP 端点并让 AI Agent 创建、查询和管理下载任务？

如果你希望 AI Agent（例如 OpenCode、Codex、Claude Code、Cursor）通过自然语言操作 Gopeed，需要完成两件事：在 Gopeed 服务上启用 MCP 端点，再把端点地址和认证信息配置到 Agent 侧。Gopeed 的 MCP 端点随内置 API/Web 服务一起提供，路径固定为 /mcp；启用后，Agent 可以调用 resolve_task、create_task、list_tasks 等 9 个工具，对 HTTP/HTTPS、BitTorrent、magnet 和 ed2k 下载任务进行解析、创建、查询和管理。以下路径以 Gopeed 的 Web 服务端（cmd/web 构建产物，即 Docker 镜像）为主要操作对象，桌面客户端的设置入口在文末补充。

准备条件

• Gopeed Web 服务端二进制（cmd/web 构建），或官方 Docker 镜像；
• Go 1.25+（仅从源码自行构建时需要，见 README.md 的 Development 一节）；
• 一个支持 MCP（streamable-http 传输）的 Agent 客户端；
• 如果端点设置了 API token，Agent 侧必须携带该 token，否则请求会被拒绝。

MCP 端点不是一个独立进程：/mcp 路由挂载在 Gopeed 的 API/Web 服务上（pkg/rest/server.go），所以「启用 MCP」=「启动 Web 服务端并打开 MCP 开关」。

第一步：启动服务并启用 MCP 端点

--mcp-enable 默认值为 false，不显式打开时 /mcp 路由返回 404（cmd/web/flags.go）。启动命令中必须带上该参数：

./gopeed --mcp-enable -P 9999

• --mcp-enable：开启 /mcp 路由；
• -P 9999：绑定端口，默认 9999；-A/--address 可指定绑定地址，默认 0.0.0.0。

如果 Agent 不在本机、需要跨网络访问，建议同时设置 API token（--api-token / -T），防止端点被匿名访问：

./gopeed --mcp-enable -P 9999 --api-token '你的token'

同一组参数也可以写入工作目录下的配置文件（默认路径 ./config.json），对应字段名为 mcpEnable、port、apiToken（cmd/web/flags.go 中 args 结构体的 json 标签）。命令行参数优先级高于配置文件。

使用 Docker 的等价方式

Docker 镜像基于 Dockerfile（FROM golang:1.25.4-alpine3.22 构建 cmd/web 二进制，EXPOSE 9999），由 entrypoint.sh 以 exec su-exec ${PUID}:${PGID} ./gopeed "$@" 方式启动，命令行参数会原样透传给 gopeed 进程，两种写法都可以：

docker run -d -p 9999:9999 \
  -v gopeed-storage:/app/storage \
  gopeed \
  --mcp-enable --api-token '你的token'

或者使用 GOPEED_ 前缀的环境变量（cmd/web/flags.go 的 loadEnvVars 会读取，键名为 GOPEED_ + 字段 json 标签的大写形式）：

docker run -d -p 9999:9999 \
  -v gopeed-storage:/app/storage \
  -e GOPEED_MCP_ENABLE=true \
  -e GOPEED_API_TOKEN='你的token' \
  gopeed

启动成功后，服务端会打印监听地址（文档示例输出，见 cmd/server.go）：

Server start success on http://0.0.0.0:9999

把 0.0.0.0 换成本机 IP 或容器宿主机 IP，MCP 端点地址即为 http://<服务器IP>:9999/mcp。

第二步：用 curl 验证端点状态

在 Agent 接入之前，先用 curl 确认端点行为符合预期。以下命令对应仓库测试 TestMCPRouteToggle 的判定逻辑（pkg/rest/server_test.go）：

curl -i -X POST 'http://<服务器IP>:9999/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer 你的token' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.0.0"}}}'

各状态的含义（均来自测试中的断言）：

状态	说明
200	端点已启用且认证通过，Agent 可以接入
401	设置了 token 但请求未携带或 token 错误
404	--mcp-enable 未开启，路由未挂载

认证只认 token 头：Authorization: Bearer <token> 或 X-Api-Token: <token> 二选一（pkg/rest/server.go 的 validateAPITokenHeaders）。需要特别注意：/mcp 属于受保护路径，Web 登录产生的会话 Cookie 对 MCP 请求无效；并且如果设置了 Web 认证账号（-u/-p）却没有设置 --api-token，MCP 端点对任何请求都返回 401。也就是说，只要 Agent 要跨网络访问，必须显式配置 --api-token。

第三步：把 Gopeed 配置到 Agent

连接配置有两种来源，任选其一。

方式一：从 Gopeed 设置界面复制配置片段

Gopeed 的设置页提供 MCP 开关（开关项文案为 “Collaborate with AI agents and explore limitless possibilities”）和 “Connect MCP agent” 对话框（ui/flutter/lib/features/settings/presentation/widgets/mcp_agent_setup.dart）。对话框内置 14 种 Agent 的模板：Codex、Claude Code、Cursor、GitHub Copilot、Windsurf、Gemini CLI、Cline、OpenCode、TRAE、Qoder、WorkBuddy、ZCode、DeepSeek Harness、Pi。选择对应 Agent 后一键复制片段即可；如果端点处于关闭状态，对话框会显示 “The MCP service is not enabled. Please enable it” 的提示。

方式二：手工编写配置片段

端点地址格式为 http://<服务器IP>:<端口>/mcp。以 OpenCode 为例（结构与上述对话框生成的片段一致，<服务器IP> 和端口替换为你实际启动时的值）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "gopeed": {
        "type": "remote",
        "url": "http://<服务器IP>:9999/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "Bearer <你的token>"
        }
      }
    }
  }
}

Codex 的等价注册方式（来自同一对话框模板，<你的token> 替换为你设置的 --api-token 值）：

export GOPEED_API_TOKEN='<你的token>'

codex mcp add gopeed --url 'http://<服务器IP>:9999/mcp' \
  --bearer-token-env-var GOPEED_API_TOKEN

其他 Agent 的字段名差异较大（如 Cline 用 type: "streamableHttp"、GitHub Copilot 用根键 servers + type: "http"），优先使用设置界面生成的片段，避免手工拼错字段。

第四步：Agent 可用的 9 个 MCP 工具

工具清单与 README 的 AI Integration 一栏一致（README.md），实现见 pkg/mcpserver/server.go：

工具	说明
resolve_task	解析下载 URL/URI（HTTP、HTTPS、magnet、torrent、ed2k），返回资源元数据和文件列表，用于创建任务前检查或选择文件
create_task	创建并启动下载任务。接受 resolve_task 返回的资源 ID（rid）或直接传下载请求（req），二者必须至少提供一个
list_tasks	列出任务，可按 ID 或状态筛选：ready、running、pause、wait、error、done
get_task	获取单个任务的请求、资源、选项和当前进度
get_task_status	获取轻量级运行时状态和逐文件进度
get_task_stats	获取协议相关统计，如 HTTP 连接数、BitTorrent peer 和做种数据
pause_task	暂停一个任务
continue_task	继续一个暂停或失败的任务
delete_task	删除一个任务；force 为 true 时同时删除已下载的文件，请谨慎使用

一次典型的对话流程：

1. 用户给出链接 → Agent 调用 resolve_task 拿到文件名和大小（多文件资源时先让用户通过 opts.selectFiles 选择要下载的文件索引）；
2. create_task 创建任务，返回任务 id；
3. 轮询 get_task_status 查看进度；
4. 需要时用 pause_task / continue_task / delete_task 管理任务。

两个容易触发的参数校验（serverInstructions 与 validateExtra 定义在 pkg/mcpserver/server.go）：

• req.extra 里的 BitTorrent 设置（trackers）只允许用于 magnet / torrent 资源；HTTP 专属设置（method、header、body）只允许用于 HTTP/HTTPS URL，传错协议会直接返回工具错误；
• 服务端内置指令要求 Agent：用户没有提供具体 URL 时必须询问，而不是自行编造下载地址。

验证结果与限制

• 端点启用且 token 正确时，上文的 curl 请求返回 200；关闭 --mcp-enable 再请求返回 404——这两个状态码可以直接用作启停验证；
• Agent 连接后调用 list_tasks 能返回任务数组（首次无任务时为空数组），说明工具链路完整（测试 TestStreamableHTTPTools 的验证方式，pkg/mcpserver/server_test.go）；
• MCP handler 是无状态（stateless）Streamable HTTP 实现（pkg/mcpserver/server.go 的 NewHandler）；
• 携带其他来源 Origin 头的跨域请求会被拒绝（TestStreamableHTTPRejectsCrossOriginRequest 断言返回 403），端点应通过 token 保护而不是依赖网络隔离；
• 删除任务时 force: true 会删除磁盘上的已下载文件，该操作不可恢复。

端点返回 200 且 Agent 能列出 Gopeed 的任务，即表示集成完成；后续新增或修改 token 后，重跑一次上文的 curl 检查即可确认端点状态。