mirror of
https://github.com/jxxghp/MoviePilot.git
synced 2026-06-15 12:40:35 +08:00
298 lines
10 KiB
Markdown
298 lines
10 KiB
Markdown
# MoviePilot MCP (Model Context Protocol) API 文档
|
||
|
||
MoviePilot 实现了标准的 **Model Context Protocol (MCP)**，允许 AI 智能体（如 Claude, GPT 等）直接调用 MoviePilot 的功能进行媒体管理、搜索、订阅和下载。
|
||
|
||
## 1. 基础信息
|
||
|
||
* **基础路径**: `/api/v1/mcp`
|
||
* **协议版本**: `2025-11-25, 2025-06-18, 2024-11-05`
|
||
* **传输协议**: HTTP (JSON-RPC 2.0)
|
||
* **认证方式**:
|
||
* Header: `X-API-KEY: <你的API_KEY>`
|
||
* Query: `?apikey=<你的API_KEY>`
|
||
|
||
## 2. 标准 MCP 协议 (JSON-RPC 2.0)
|
||
|
||
### 端点
|
||
**POST** `/api/v1/mcp`
|
||
|
||
### 支持的方法
|
||
- `initialize`: 初始化会话，协商协议版本和能力。
|
||
- `notifications/initialized`: 客户端确认初始化完成。
|
||
- `tools/list`: 获取可用工具列表。
|
||
- `tools/call`: 调用特定工具。
|
||
- `ping`: 连接存活检测。
|
||
|
||
---
|
||
|
||
## 4. 客户端配置示例
|
||
|
||
### Claude Desktop (Anthropic)
|
||
|
||
在Claude Desktop的配置文件中添加MoviePilot的MCP服务器配置：
|
||
|
||
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
||
|
||
使用请求头方式：
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"moviepilot": {
|
||
"url": "http://localhost:3001/api/v1/mcp",
|
||
"headers": {
|
||
"X-API-KEY": "your_api_key_here"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
或使用查询参数方式：
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"moviepilot": {
|
||
"url": "http://localhost:3001/api/v1/mcp?apikey=your_api_key_here"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. 错误码说明
|
||
|
||
| 错误码 | 消息 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| -32700 | Parse error | JSON 格式错误 |
|
||
| -32600 | Invalid Request | 无效的 JSON-RPC 请求 |
|
||
| -32601 | Method not found | 方法不存在 |
|
||
| -32602 | Invalid params | 参数验证失败 |
|
||
| -32002 | Session not found | 会话不存在或已过期 |
|
||
| -32003 | Not initialized | 会话未完成初始化流程 |
|
||
| -32603 | Internal error | 服务器内部错误 |
|
||
|
||
## 6. RESTful API
|
||
所有工具相关的API端点都在 `/api/v1/mcp` 路径下（保持向后兼容）。
|
||
|
||
### 相关 REST 端点
|
||
|
||
MoviePilot 也提供普通 REST API 给前端和自动化客户端使用。所有接口同样需要 API KEY 认证，在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`。
|
||
|
||
#### 搜索 / 种子 / 字幕
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| GET | `/api/v1/search/media/{mediaid}` | 按媒体 ID 搜索站点种子资源，`mediaid` 支持 `tmdb:123`、`douban:123`、`bangumi:123`，参数：`mtype`、`area`、`title`、`year`、`season`、`sites` |
|
||
| GET | `/api/v1/search/media/{mediaid}/stream` | 按媒体 ID 渐进式搜索站点种子资源，返回 SSE，参数同上 |
|
||
| GET | `/api/v1/search/title` | 按关键字模糊搜索站点种子资源，参数：`keyword`、`page`、`sites` |
|
||
| GET | `/api/v1/search/title/stream` | 按关键字渐进式搜索站点种子资源，返回 SSE，参数：`keyword`、`page`、`sites` |
|
||
| GET | `/api/v1/search/subtitle/title` | 按关键字搜索站点字幕资源，参数：`keyword`、`page`、`sites` |
|
||
| GET | `/api/v1/search/subtitle/title/stream` | 按关键字渐进式搜索站点字幕资源，返回 SSE，参数：`keyword`、`page`、`sites` |
|
||
| GET | `/api/v1/search/subtitle/media/{mediaid}` | 按媒体 ID 精确搜索站点字幕资源，`mediaid` 支持 `tmdb:123`、`douban:123`、`bangumi:123`，参数：`mtype`、`title`、`year`、`season`、`episode`、`sites` |
|
||
| GET | `/api/v1/search/subtitle/media/{mediaid}/stream` | 按媒体 ID 渐进式精确搜索站点字幕资源，返回 SSE，参数同上 |
|
||
| GET | `/api/v1/search/last` | 获取上一次种子搜索结果 |
|
||
| GET | `/api/v1/search/last/context` | 获取上一次搜索结果及可复用搜索参数，`params.result_type` 为 `torrent` 或 `subtitle` |
|
||
| POST | `/api/v1/search/recommend` | 获取 AI 推荐资源，请求体：`filtered_indices`、`check_only`、`force` |
|
||
|
||
#### 下载
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| GET | `/api/v1/download/` | 查询正在下载的任务，参数：`name` |
|
||
| POST | `/api/v1/download/` | 添加含媒体信息的下载任务，请求体包含媒体信息和种子信息 |
|
||
| POST | `/api/v1/download/add` | 添加不含媒体信息的下载任务，请求体包含 `torrent_in`，可选 `tmdbid`、`doubanid`、`downloader`、`save_path` |
|
||
| POST | `/api/v1/download/subtitle` | 下载字幕到识别出的媒体下载目录，请求体包含 `subtitle_in`，可选 `tmdbid`、`doubanid`、`save_path` |
|
||
| GET | `/api/v1/download/start/{hashString}` | 恢复下载任务，参数：`name` |
|
||
| GET | `/api/v1/download/stop/{hashString}` | 暂停下载任务，参数：`name` |
|
||
| GET | `/api/v1/download/clients` | 查询可用下载器 |
|
||
| GET | `/api/v1/download/paths` | 查询可用于下载接口 `save_path` 参数的下载路径 |
|
||
| DELETE | `/api/v1/download/{hashString}` | 删除下载任务，参数：`name` |
|
||
|
||
#### 系统
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| GET | `/api/v1/system/ping` | 登录用户服务存活检测，用于前端重启后轮询恢复状态 |
|
||
| GET | `/api/v1/system/setting/public/{key}` | 登录用户读取白名单内非敏感系统设置，仅支持目录、存储、站点范围、默认订阅规则、Follow 订阅者和插件市场地址等前端必需配置 |
|
||
| POST | `/api/v1/system/setting/PLUGIN_MARKET/sync-wiki` | 管理员从 MoviePilot Wiki 的插件文档同步公开插件仓库清单，和本地 `PLUGIN_MARKET` 合并去重后写入配置 |
|
||
|
||
### 插件补充接口
|
||
|
||
**GET** `/api/v1/plugin/history/{plugin_id}`
|
||
|
||
按需读取指定已安装插件的最新远端更新说明。该接口用于前端在用户点击“查看更新说明”时再实时访问插件仓库，避免加载已安装插件列表时批量请求网络。
|
||
|
||
### 1. 列出所有工具
|
||
|
||
**GET** `/api/v1/mcp/tools`
|
||
|
||
获取所有可用的MCP工具列表。
|
||
|
||
**认证**: 需要API KEY，在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`
|
||
|
||
**响应示例**:
|
||
```json
|
||
[
|
||
{
|
||
"name": "add_subscribe",
|
||
"description": "Add media subscription to create automated download rules...",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"title": {
|
||
"type": "string",
|
||
"description": "The title of the media to subscribe to"
|
||
},
|
||
"year": {
|
||
"type": "string",
|
||
"description": "Release year of the media"
|
||
},
|
||
...
|
||
},
|
||
"required": ["title", "year", "media_type"]
|
||
}
|
||
},
|
||
...
|
||
]
|
||
```
|
||
|
||
### 2. 调用工具
|
||
|
||
**POST** `/api/v1/mcp/tools/call`
|
||
|
||
调用指定的MCP工具。
|
||
|
||
**认证**: 需要API KEY，在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"tool_name": "add_subscribe",
|
||
"arguments": {
|
||
"title": "流浪地球",
|
||
"year": "2019",
|
||
"media_type": "movie"
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"result": "成功添加订阅：流浪地球 (2019)",
|
||
"error": null
|
||
}
|
||
```
|
||
|
||
**错误响应示例**:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"result": null,
|
||
"error": "调用工具失败: 参数验证失败"
|
||
}
|
||
```
|
||
|
||
**`search_web` 网络搜索示例**:
|
||
```json
|
||
{
|
||
"tool_name": "search_web",
|
||
"arguments": {
|
||
"query": "asyncio TaskGroup",
|
||
"search_engine": "duckduckgo",
|
||
"site_url": "https://docs.python.org/3/",
|
||
"max_results": 5
|
||
}
|
||
}
|
||
```
|
||
|
||
`search_engine` 可选，通过 DDGS 支持 `auto`、`duckduckgo`、`google`、`brave`、`yahoo`、`wikipedia`、`yandex`、`mojeek`。`site_url` 可选，用于限定搜索到指定域名或 URL 路径范围。搜索默认使用系统代理配置。
|
||
|
||
**`browse_webpage` 浏览器操作示例**:
|
||
```json
|
||
{
|
||
"tool_name": "browse_webpage",
|
||
"arguments": {
|
||
"action": "goto",
|
||
"url": "https://example.com"
|
||
}
|
||
}
|
||
```
|
||
|
||
`browse_webpage` 使用持久浏览器会话，默认以当前 Agent 会话作为 `session_key`。`goto`、`snapshot`、`click`、`click_ref`、`fill`、`fill_ref`、`select`、`select_ref`、`wait` 等动作会返回页面快照，快照中的 `interactive_elements[].ref` 可用于后续 `*_ref` 操作。支持 `list_tabs`、`open_tab`、`focus_tab`、`close_tab` 管理标签页，支持 `close_session` 释放会话。出于安全考虑，默认拒绝访问 localhost、环回地址、私网地址和链路本地地址；确需访问可信内网或本机页面时，可显式传入 `allow_private_network: true`。
|
||
|
||
**`recognize_captcha` 图形验证码识别示例**:
|
||
```json
|
||
{
|
||
"tool_name": "recognize_captcha",
|
||
"arguments": {
|
||
"image_url": "https://example.com/captcha.png",
|
||
"cookie": "sid=...",
|
||
"user_agent": "Mozilla/5.0 ..."
|
||
}
|
||
}
|
||
```
|
||
|
||
`recognize_captcha` 用于浏览器自动化登录时识别普通图形验证码。智能体可先通过 `browse_webpage` 的 `evaluate` 动作从页面元素中提取 `img.src`，再把图片地址传给该工具；支持 `http/https` 图片地址和 `data:image/...;base64,...`。当验证码图片依赖当前浏览器会话时，可传入 Cookie 与 User-Agent。出于安全考虑，默认拒绝访问 localhost、环回地址、私网地址和链路本地地址；确需访问可信内网或本机验证码图片时，可显式传入 `allow_private_network: true`。
|
||
|
||
### 3. 获取工具详情
|
||
|
||
**GET** `/api/v1/mcp/tools/{tool_name}`
|
||
|
||
获取指定工具的详细信息。
|
||
|
||
**认证**: 需要API KEY，在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`
|
||
|
||
**路径参数**:
|
||
- `tool_name`: 工具名称
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"name": "add_subscribe",
|
||
"description": "Add media subscription to create automated download rules...",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"title": {
|
||
"type": "string",
|
||
"description": "The title of the media to subscribe to"
|
||
},
|
||
...
|
||
},
|
||
"required": ["title", "year", "media_type"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 获取工具参数Schema
|
||
|
||
**GET** `/api/v1/mcp/tools/{tool_name}/schema`
|
||
|
||
获取指定工具的参数Schema（JSON Schema格式）。
|
||
|
||
**认证**: 需要API KEY，在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`
|
||
|
||
**路径参数**:
|
||
- `tool_name`: 工具名称
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"title": {
|
||
"type": "string",
|
||
"description": "The title of the media to subscribe to"
|
||
},
|
||
"year": {
|
||
"type": "string",
|
||
"description": "Release year of the media"
|
||
},
|
||
...
|
||
},
|
||
"required": ["title", "year", "media_type"]
|
||
}
|
||
```
|