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 再搜片，一步完成。 不要再开话题问配置。

备用：终端配置#

bash

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

调用方式#

bash

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），需跳过前缀提取

核心工具速查#

类别工具说明🔍 搜索search_mediaTMDB 搜索影视/动漫/纪录片🔍 搜索recognize_media从种子标题或文件路径提取媒体信息🔍 搜索query_media_detail获取详情：状态/类型/演职员/分季信息🔍 搜索get_recommendations热门/新片/口碑推荐🔍 搜索search_person搜索演员/导演等影人🔍 搜索search_person_credits查询影人参演作品列表🔍 搜索query_episode_schedule剧集播出日历/更新进度📥 订阅add_subscribe新建订阅，自动追更/下载📥 订阅query_subscribes查看全部订阅及状态📥 订阅search_subscribe立即搜索缺失剧集📥 订阅update_subscribe改状态/过滤/集数/质量📥 订阅delete_subscribe删除订阅📥 订阅query_subscribe_shares社区分享的订阅推荐📥 订阅query_popular_subscribes全站热门订阅排行📥 订阅query_subscribe_history订阅搜索历史⬇️ 下载search_torrents跨站点搜索种子资源⬇️ 下载get_search_results浏览缓存的搜索结果⬇️ 下载add_download提交下载任务⬇️ 下载query_download_tasks查看下载进度/状态⬇️ 下载modify_download暂停/恢复/打标签⬇️ 下载delete_download删除下载（可含文件）⬇️ 下载delete_download_history清理下载历史⬇️ 下载query_downloaders查看已配置的下载器📂 整理transfer_file整理文件到媒体库📂 整理query_library_exists检查是否已在库📂 整理query_library_latest最近入库媒体📂 整理scrape_metadata刮削 NFO/海报/背景📂 整理query_transfer_history整理历史📂 整理delete_transfer_history清除整理记录📂 整理list_directory浏览文件目录📂 整理query_directory_settings查看目录分类设置🌐 站点query_sites列出所有 PT 站点🌐 站点update_site修改站点配置🌐 站点query_site_userdata站点用户数据（上传/下载量等）🌐 站点test_site测试站点连通性🌐 站点update_site_cookie刷新/更新站点登录🧩 规则query_custom_filter_rules自定义过滤规则🧩 规则query_rule_groups过滤规则组🧩 规则query_builtin_filter_rules系统内置规则🧩 规则add_custom_filter_rule新增过滤规则🧩 规则add_rule_group新建规则组🧩 规则update_custom_filter_rule / delete_custom_filter_rule编辑/删除规则🧩 规则update_rule_group / delete_rule_group编辑/删除规则组🔌 插件query_installed_plugins已装插件🔌 插件query_market_plugins插件市场搜索🔌 插件query_plugin_config / update_plugin_config查看/修改插件配置🔌 插件install_plugin / uninstall_plugin安装/卸载插件🔌 插件reload_plugin重载插件🔌 插件query_plugin_data读取插件数据🔌 插件query_plugin_capabilities插件能力查询⚙️ 系统query_system_settings / update_system_settings系统配置⚙️ 系统query_schedulers / run_scheduler定时任务⚙️ 系统query_workflows / run_workflow工作流管理⚙️ 系统send_message / send_local_file发送通知/本地文件⚙️ 系统browse_webpage浏览网页👤 人格query_personas / switch_persona / update_persona_definitionPersona 管理⌨️ 快捷list_slash_commands / run_slash_command快捷指令🏷️ 标识query_custom_identifiers / update_custom_identifiers自定义识别词

常用工作流#

1. 搜片 → 订阅#

text

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

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

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

text

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

3. 管订阅#

text

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

4. 检查媒体库#

text

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

5. 维护 PT 站点#

text

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。