内容
# MPilot
**统一的MCP服务器，用于媒体获取、字幕自动化和代理运行的媒体工作流。**
MPilot适用于已经运行Plex、Jellyfin、Emby、qBittorrent或普通本地媒体文件夹的人员，并希望有一个代理或机器人来处理以下请求：
> 下载这部电影并在准备好时制作中英字幕。
它在一個项目后面结合了三个工具集：
- **获取** - 识别电影或节目，搜索Prowlarr，排名发布，并将选定的结果排队到qBittorrent。
- **字幕** - 从侧车、嵌入式文本轨道、Plex元数据或在线提供商查找源字幕，然后翻译并写入SRT/ASS侧车。
- **运行时** - 记住长期运行的下载/字幕意图，以便代理可以在原始聊天回合结束后继续工作。
通过`mpilot-mcp`一起使用这三个工具，或仅在需要独立字幕插件时启用字幕工具。
## 功能
- 接受IMDb ID/URL、支持的豆瓣或爱奇艺电影链接或普通的自然语言标题。
- 以代理友好的结构化数据返回标题和发布选择。
- 通过qBittorrent的Web UI API将下载排队到您自己的qBittorrent中。
- 渲染聊天准备好的下载进度卡和完成通知。
- 翻译现有的`.srt`文件或具有嵌入/源字幕的视频文件。
- 在本地源字幕丢失时搜索配置的字幕提供商。
- 写入Plex兼容的侧车，如`Movie.zh.srt`或`Movie.zh.ass`。
- 为Claude Desktop、Cursor、Hermes、Cline、OpenClaw、ChatGPT MCP桥、Telegram机器人或自定义代理公开一个MCP服务器。
MPilot不提供媒体、索引器、跟踪器、字幕提供商帐户或法律建议。仅在您允许使用的服务和内容中使用它。
## 运行环境
完整的媒体获取需要：
- Python 3.12+
- Prowlarr用于洪流索引器搜索
- 启用Web UI的qBittorrent
- 可选的FlareSolverr用于Cloudflare保护的Prowlarr索引器
仅字幕使用需要：
- Python 3.12+
- `ffmpeg`和最好是`ffprobe`用于本地视频探测
- 翻译后端，如Codex CLI或OpenAI兼容的端点
- 可选的Plex URL/令牌用于库查找
- 可选的OpenSubtitles.com或SubDL凭证用于在线字幕备用
本地侧车和嵌入式字幕工作流程不需要Prowlarr、qBittorrent、Plex、OpenSubtitles或SubDL。
## 快速入门
```sh
git clone https://github.com/davezfr/mpilot.git
cd mpilot
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[all]"
cp .env.example .env
```
用于开发：
```sh
python -m pip install -e ".[all,dev]"
python -m pytest -q
```
## 使用感受
当完整的工具集连接到同一个代理时，一个自然语言请求可以通过获取、下载跟踪、字幕源选择、翻译和侧车回写。
<table>
<tr>
<td width="48.4%" align="center" valign="middle">
<img src="assets/readme/telegram-download-and-subtitle-one-shot.jpg" height="420" alt="Telegram示例：一个请求下载《他的女朋友》并准备中英字幕。">
</td>
<td width="51.6%" align="center" valign="middle">
<img src="assets/readme/bilingual-ass-his-girl-friday.jpg" height="420" alt="《他的女朋友》的中英双语ASS字幕输出。">
</td>
</tr>
</table>
*截图仅供参考。演示使用的是公共领域标题；权利可能因司法管辖区和特定修复、配乐、字幕或版本而异。*
```text
用户：
下载《他的女朋友》并制作中英字幕。
代理：
1. 调用media_request并带有标题和字幕意图。
2. MPilot识别标题，搜索Prowlarr，并排队最佳匹配。
3. 运行时在qBittorrent下载时存储字幕意图。
4. 当本地视频路径准备好时，MPilot创建并启动字幕作业。
5. 用户获得一个工作流状态，而不是单独的下载/字幕任务。
结果：
媒体文件被下载，MPilot在视频旁边或在配置的输出位置写入字幕侧车，如Movie.zh.ass。
```
对于不需要字幕的直接获取，MPilot还可以返回发布选择和进度卡：
<p align="center">
<img src="assets/readme/telegram-imdb-release-picker.jpg" width="54%" alt="Telegram示例：分享IMDb页面，选择发布，查看MPilot下载进度。">
</p>
对于仅字幕使用，指向MPilot现有的视频或Plex项目：
<p align="center">
<img src="assets/readme/telegram-subtitle-after-download-ready.jpg" width="70%" alt="Telegram示例：在下载可用后请求字幕。">
</p>
## 配置获取
获取是MPilot的Prowlarr -> qBittorrent部分。
1. 启用qBittorrent Web UI并记录URL、用户名和密码。
2. 启动或指向MPilot的Prowlarr，然后添加您允许使用的索引器。
3. 在`.env`中填写这些值：
```sh
MPILOT_PROWLARR_URL=http://prowlarr:9696
MPILOT_PROWLARR_API_KEY=替换为prowlarr-api-key
MPILOT_ACQUISITION_API_KEY=替换为一个长随机密钥
MPILOT_QBIT_URL=http://host.docker.internal:8080
MPILOT_QBIT_USERNAME=替换为webui-username
MPILOT_QBIT_PASSWORD=替换为webui-password
MPILOT_ACQUISITION_SAVE_PATH_MOVIE=/downloads/movies
MPILOT_ACQUISITION_SAVE_PATH_MOVIE_4K=/downloads/movies-4k
MPILOT_ACQUISITION_SAVE_PATH_TV=/downloads/tv
# 示例：首先发现您自己的Prowlarr实例的ID。
MPILOT_PROWLARR_IMDB_NATIVE_INDEXER_IDS=5,6
MPILOT_PROWLARR_IMDB_KEYWORD_INDEXER_IDS=4
MPILOT_PROWLARR_IMDB_DISABLED_INDEXER_IDS=1,3
MPILOT_PROWLARR_COMPLEMENTARY_INDEXER_IDS=
```
## 配置字幕
字幕工作流程可以仅使用本地文件或与Plex/提供商集成。
```sh
MPILOT_SUBTITLE_BACKEND=codex-cli
MPILOT_SUBTITLE_MODEL=gpt-5.4-mini
MPILOT_SUBTITLE_SOURCE_LANGUAGE=en
MPILOT_SUBTITLE_TARGET_LANGUAGE=zh
MPILOT_SUBTITLE_OUTPUT_MODE=bilingual-ass
```
可选的Plex查找：
```sh
PLEX_BASE_URL=http://127.0.0.1:32400
PLEX_TOKEN=替换为token
MPILOT_PLEX_PATH_PREFIX=/server/media
MPILOT_LOCAL_PATH_PREFIX=/mnt/media
```
可选的在线字幕提供商：
```sh
OPENSUBTITLES_API_KEY=替换为密钥
OPENSUBTITLES_USER_AGENT="MPilot v0.1.0"
OPENSUBTITLES_USERNAME=替换为用户名
OPENSUBTITLES_PASSWORD=替换为密码
SUBDL_API_KEY=替换为密钥
```
## MCP设置
为新的集成使用`mpilot-mcp`。
```json
{
"command": "/绝对路径/to/mpilot/bin/mpilot-mcp",
"env": {
"MPILOT_ENABLE_ACQUISITION_TOOLS": "true",
"MPILOT_ENABLE_SUBTITLE_TOOLS": "true",
"MPILOT_PROWLARR_URL": "http://127.0.0.1:9696",
"MPILOT_PROWLARR_API_KEY": "替换为密钥",
"MPILOT_QBIT_URL": "http://127.0.0.1:8080",
"MPILOT_QBIT_USERNAME": "替换为用户",
"MPILOT_QBIT_PASSWORD": "替换为密码",
"PLEX_BASE_URL": "http://127.0.0.1:32400",
"PLEX_TOKEN": "替换为令牌"
}
}
```
关键工具：
- `media_request` - 一个用于获取和可选字幕意图的请求。
- `acquisition_handle` - 识别/搜索媒体并返回发布选择。
- `acquisition_download` - 排队选择的发布。
- `acquisition_render_downloads_status` - 返回聊天准备好的进度卡。
- `job_create_video` - 为直接本地视频路径创建字幕作业。
- `job_start` / `job_show` - 运行和检查字幕作业。
- `queue_status` / `workflow_show` - 检查长期运行的工作流状态。
原始运行时存储工具默认禁用；受信任的操作员集成可以通过`MPILOT_ENABLE_RUNTIME_OPERATOR_TOOLS=true`启用。破坏性的获取控制同样通过`MPILOT_ENABLE_ACQUISITION_CONTROL_TOOLS=true`选择启用。对于不受信任或请求者范围的MCP客户端，保持两者禁用。
## CLI示例
```sh
# 统一的CLI调度器
mpilot --help
# 使用本地/嵌入式/提供商字幕翻译现有的视频
mpilot subtitles translate-video "/mnt/media/Movies/Movie.mkv" \
--source-language en \
--target-language zh \
--output-mode bilingual-ass
# 为代理或机器人创建持久的字幕作业
mpilot subtitles job-create-video \
--video-path "/mnt/media/Movies/Movie.mkv" \
--title "Movie" \
--media-type movie \
--source-language en \
--target-language zh
# 检查运行时工作流状态
mpilot runtime queue-status
```
## 迁移自qBitlarr和Babelarr
MPilot取代了单独的qBitlarr和Babelarr存储库。这些项目存档并保留历史记录；新工作在这里进行。
对于新的集成：
- 使用`mpilot-mcp`，而不是旧的每个项目MCP启动器。
- 使用`media_request`进行组合下载和字幕意图。
- 使用`acquisition_*`工具进行仅下载工作流。
- 使用`job_*`、`plex_search`和`subtitle_plan`进行仅字幕工作流。
- 优先使用`MPILOT_*`环境变量。
## 责任使用
MPilot是一个自动化层。它不包括媒体、字幕提供商帐户、索引器、跟踪器或法律建议。仅在您的司法管辖区中您允许访问的内容、索引器和字幕提供商中使用它。
## 第三方项目
MPilot与或可以调用这些工具和服务集成：
- [Prowlarr](https://github.com/Prowlarr/Prowlarr) 用于索引聚合。
- [qBittorrent](https://github.com/qbittorrent/qBittorrent) 通过其Web UI API。
- [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) 作为Prowlarr索引器的可选挑战代理。
- Plex、Jellyfin、Emby或本地媒体文件夹作为库目标。
- OpenSubtitles.com和SubDL作为可选字幕提供商。
- Codex CLI或OpenAI兼容的端点作为翻译后端。
MPilot与这些项目或其维护者无关、未获得其认可或赞助。
