MoviePilot MCP

通过 MoviePilot 的 MCP 接口操控 NAS 媒体库自动化系统。覆盖电影、电视剧、动漫、纪录片等全部媒体类型。

前置配置（对话中完成，不需要终端）

首次使用时如果未配置 config.json，AI 在对话中直接向用户获取两个信息：

1. 先问 MoviePilot 服务器地址 — 格式 http://IP:端口，默认端口 3001
2. 再问 API 密钥 — MoviePilot 的 API_TOKEN

拿到后写入 config.json，然后继续执行用户原本的请求。用户全程无需切换终端。

如何引导用户找 API Key

用户找不到时告诉 ta 任一方式：

• MoviePilot Web UI → 系统设定 → 查看 API_TOKEN
• Docker：docker inspect <容器名> | grep API_TOKEN
• docker-compose.yml 中 environment.API_TOKEN
• 容器启动日志：docker logs <容器名> | grep -i token
• V1 默认值 moviepilot；V2 要求 ≥16 个字符，不满足会自动重新生成

详见 references/setup-guide.md。

一步到位

如果用户在首次请求时就把信息给了：

"服务器 192.168.1.100:3001，Key 是 xxx，帮我搜流浪地球"

AI 先写 config.json 再搜片，一步完成。不要再开话题问配置。

备用：终端配置

python3 scripts/setup.py                     # 交互式向导
python3 scripts/setup.py '{"base_url":"http://IP:3001","apikey":"***"}'  # 一键写入

调用方式

python3 scripts/mp_call.py <tool_name> '<json_args>'

# 例：
python3 scripts/mp_call.py search_media '{"title":"流浪地球","media_type":"movie"}'
python3 scripts/mp_call.py query_subscribes '{}'

JSON 参数要点：

• 空参数：'{}'
• 字符串：'{"title":"三体","media_type":"tv"}'
• 数字/布尔：不加引号 — {"tmdb_id":535167,"overwrite":true}
• 数组：'{"sites":[2,3],"filter_groups":["BluRay","WEB-DL"]}'
• 结果取 result.content[0].text，部分工具返回带分页前缀（如 第 1/1 页… + JSON），需跳过前缀提取

核心工具速查

常用工作流

1. 搜片 → 订阅

search_media（拿到 tmdb_id + year + media_type）
  → add_subscribe
  → query_subscribes 确认 / search_subscribe 立即搜

• 电视剧 year 必传；season 不传默认仅 S1，多季逐季调用
• media_type：电影 "movie"，剧集 "tv"

2. 手动搜种 → 下载 → 入库

search_torrents → get_search_results → add_download
  → query_download_tasks（看进度）
  → transfer_file（入库）

3. 管订阅

query_subscribes → 找 subscribe_id
  → search_subscribe  补缺
  → update_subscribe  改过滤/状态（R=启用 P=待定 S=暂停）
  → delete_subscribe  删除

4. 检查媒体库

query_library_exists + tmdb_id → 是否已有
query_library_latest → 最近入库

5. 维护 PT 站点

query_sites → 找站点标识
  → test_site 测试连通 / update_site_cookie 更新登录 / update_site 改配置

注意事项

• add_subscribe 的 filter_groups 传规则组名称数组，不是 id
• transfer_file 的 file_path 须是 MoviePilot 容器内可见路径
• quality/resolution/effect 过滤用正则，| 分隔多选项
• 部分工具 text 带分页前缀，解析 JSON 前须跳过

全部 70 个工具参数 → references/tools.md，工作流实例 → references/workflows.md。