Gopeed MCP Server

一个基于 Model Context Protocol (MCP) 的 Server，让你能在各种 AI Agent / 智能体中通过自然语言控制 Gopeed 下载管理器。它遵循标准 MCP 协议，可无缝接入任意兼容 MCP 的客户端，例如 VS Code Copilot Chat、WorkBuddy、Trae 等。

关于 Gopeed：本项目的被控对象是开源下载管理器 Gopeed（由 GopeedLab 维护，采用 GPL-3.0 许可证）。本 Server 仅通过 Gopeed 公开的 REST API 与之通信，不修改、不嵌入其任何源代码，因此本仓库以 MIT 许可证独立发布。使用前请先安装并运行 Gopeed 本体。

功能介绍

本 MCP Server 封装了 Gopeed 的 REST API，提供以下 10 个工具：

环境要求

• Python 3.10+
• Gopeed 已安装并运行（API 端口每次启动随机分配，无需手动指定）
• 任意兼容 MCP 的 AI Agent / 智能体客户端（如 VS Code Copilot Chat、WorkBuddy、Trae 等）

安装步骤

1. 进入项目目录：

   cd gopeed-mcp-server
   

2. （推荐）创建虚拟环境：

   python -m venv .venv
   # Windows
   .venv\Scripts\activate
   # macOS / Linux
   source .venv/bin/activate
   

3. 安装依赖（二选一）：

   • 方式 A：从源码安装依赖

     pip install -r requirements.txt
     

   • 方式 B：作为 Python 包安装（推荐，可用于 uvx 一键启动）

     pip install gopeed-mcp-server
     

     安装后会得到 gopeed-mcp-server 命令，可用 uvx gopeed-mcp-server 直接启动。

4. （可选）配置环境变量。复制 .env.example 为 .env 并按需修改：

   copy .env.example .env
   

   可用环境变量：

   • GOPEED_API_URL：Gopeed API 地址。默认 http://127.0.0.1:7766/api/v1（端口 7766 为默认固定端口）。若你的 Gopeed 使用随机端口，可留空端口部分（如 http://127.0.0.1/api/v1），server 会自动发现 Gopeed 实际端口。
   • GOPEED_API_TOKEN：API 令牌（可选，Gopeed 配置了令牌时需要）
   • GOPEED_TIMEOUT：请求超时秒数，默认 10

客户端配置方法

以下以 VS Code Copilot Chat 为例，其他兼容 MCP 的客户端（WorkBuddy、Trae 等）配置方式类似。

手动配置 mcp.json

VS Code 1.99+ 使用专用的 mcp.json（而不是 settings.json 的 mcpServers 字段）。

1. 按 Ctrl+Shift+P，运行 MCP: Open User Configuration（或在工作区创建 .vscode/mcp.json）。

2. 添加如下配置（使用 uvx 启动，无需本地路径）：

   {
     "servers": {
       "gopeed": {
         "command": "uvx",
         "args": ["gopeed-mcp-server"],
         "env": {
           "GOPEED_API_URL": "http://127.0.0.1:7766/api/v1"
         }
       }
     }
   }
   

   若未发布到 PyPI，可改用本地源码方式：

   {
     "servers": {
       "gopeed": {
         "command": "python",
         "args": ["-m", "gopeed_mcp_server"],
         "env": {
           "GOPEED_API_URL": "http://127.0.0.1:7766/api/v1"
         }
       }
     }
   }
   

   注意：

   • GOPEED_API_URL 默认使用 http://127.0.0.1:7766/api/v1（端口 7766 为固定端口）；若使用随机端口可留空端口部分，server 会自动发现 Gopeed 当前监听端口。
   • 如果 Gopeed 配置了 API 令牌，在 env 中添加 "GOPEED_API_TOKEN": "你的令牌"。
   • Windows 沙箱（sandbox）目前不可用，本地 stdio server 直接运行。

3. 保存 mcp.json，重启 VS Code（或 Developer: Reload Window）。

4. 验证配置：打开 Copilot Chat，输入 @gopeed 或直接描述需求，Copilot 应能识别并调用 Gopeed 工具。也可在 MCP 面板中查看 gopeed server 状态。

使用示例

在任意兼容 MCP 的客户端中，你可以用自然语言这样说：

项目结构

gopeed-mcp-server/
├── src/
│   └── gopeed_mcp_server/ # Python package 源码
│       ├── __init__.py    # 包入口，导出公共 API
│       ├── __main__.py    # 支持 python -m gopeed_mcp_server 启动
│       ├── config.py      # 配置管理（从环境变量读取）
│       ├── constants.py   # 状态常量定义
│       ├── client.py      # Gopeed REST API 客户端封装
│       ├── transport.py   # HTTP 传输层（自动重发现）
│       ├── discovery.py   # 端口自动发现逻辑
│       ├── exceptions.py  # 异常类型定义
│       └── server.py      # MCP Server 主入口，定义所有 MCP Tools
├── pyproject.toml         # 打包配置（提供 gopeed-mcp-server 命令）
├── requirements.txt       # Python 依赖
├── .env.example           # 环境变量示例
├── icon.png               # 包 / 仓库图标
└── README.md              # 本文件

故障排查

1. Copilot Chat 无法调用 Gopeed 工具

• 确认 mcp.json 中 servers.gopeed 配置正确（uvx gopeed-mcp-server 或本地 python -m gopeed_mcp_server），路径使用正斜杠或双反斜杠 \\。
• 若使用本地源码方式，确认 command 指向可运行的 Python（如 ...\.venv\Scripts\python.exe 或裸 python），而非错误路径。
• 重启 VS Code 后再试。
• 在 VS Code 中打开 Output 面板，选择 MCP 通道查看 gopeed server 的日志输出。

2. 提示"无法连接到 Gopeed"

• 确认 Gopeed 已启动并正在运行。
• Gopeed 每次重启会随机分配 API 端口，本 server 默认自动发现当前端口；若 GOPEED_API_URL 写死了旧端口会失效，建议改为留空端口的 http://127.0.0.1/api/v1。
• 检查防火墙是否阻止了本地回环连接；若系统启用了代理，localhost 请求可能被拦截返回 503，本 server 已对本地请求禁用代理。

3. 提示"Gopeed 业务错误"或"HTTP 401/403"

• Gopeed 可能配置了 API 访问令牌，需要在 env 中设置 GOPEED_API_TOKEN。
• 在 Gopeed Web UI 的设置中查看是否启用了令牌认证。

4. Python 依赖安装失败

• 确保 Python 版本 >= 3.10：python --version
• 升级 pip：pip install --upgrade pip
• 使用国内镜像源：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

5. 手动测试 Gopeed API 连通性

Gopeed 端口随机，先找到当前端口再用 curl 测试：

# Windows：通过 netstat 找到 gopeed 监听的回环端口
netstat -ano | findstr "LISTENING" | findstr "gopeed"

# 假设查到端口为 12345，则：
curl http://127.0.0.1:12345/api/v1/config
curl http://127.0.0.1:12345/api/v1/tasks

如果 curl 能正常返回 JSON 数据（含 "code":0），说明 Gopeed API 正常，问题出在 MCP Server 配置或 Python 环境。

许可证

本项目（Gopeed MCP Server）以 MIT 许可证发布，详见 LICENSE。

被控对象 Gopeed 本身是独立的开源项目，采用 GPL-3.0 许可证（© GopeedLab 及其贡献者）。本 Server 仅通过网络调用其公开 REST API 进行集成，不构成对 Gopeed 源代码的修改或衍生，亦不随本仓库分发 Gopeed 的任何代码。如使用 Gopeed 本体，请遵守其对应的许可证条款。

发布与上架

本 server 已发布到以下渠道，用户可直接获取并配置：

• GitHub（已公开）：https://github.com/Panda-Young/gopeed-mcp-server —— 仓库即发布页，按上面的 mcp.json 片段手动添加即可使用。
• PyPI（已发布）：pip install gopeed-mcp-server 或直接 uvx gopeed-mcp-server，见 https://pypi.org/project/gopeed-mcp-server/ 。
• Glama：打开 https://glama.ai/mcp/register ，粘贴本仓库 URL，会自动读取仓库根的 mcp.json。
• Smithery：本地 stdio server 用 CLI 发布（非网页表单）。安装 @smithery/cli 后，在仓库目录执行 smithery login 再 smithery mcp publish . -n @Panda-Young/gopeed-mcp-server（会读取 smithery.yaml）。
• VS Code MCP Gallery：VS Code 内置的 MCP Gallery 目前为微软托管的精选列表，没有公开的投稿入口，个人开发者暂无法直接上架。用户可从上面的 GitHub / PyPI / Glama / Smithery 任一渠道获取并手动配置到 mcp.json。
• 手动分享：任何已安装本包的环境，把上面的 mcp.json 片段加入 mcp.json 即可使用。

发布新版本到 PyPI

修改 pyproject.toml 中的 version 后，重新构建并上传：

python -m build
twine upload dist/*

上传凭证请勿写入本仓库。推荐在用户目录 ~/.pypirc 配置 [pypi] 的 username = __token__ 与 password，或使用环境变量 TWINE_USERNAME / TWINE_PASSWORD。令牌从 https://pypi.org/manage/account/token/ 获取。