MoviePilot MCP

SKILL.md

---
name: moviepilot-mcp
description: "MoviePilot 媒体库自动化：搜索影视/动漫/纪录片、订阅追更、管理下载、整理入库、PT站点维护、插件管理。"
user-invocable: true
---

# 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_media` | TMDB 搜索影视/动漫/纪录片 |
| 🔍 搜索 | `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_definition` | Persona 管理 |
| ⌨️ 快捷 | `list_slash_commands` / `run_slash_command` | 快捷指令 |
| 🏷️ 标识 | `query_custom_identifiers` / `update_custom_identifiers` | 自定义识别词 |

## 常用工作流

### 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`。