archived-MoviePilot/docs/mcp-api.md

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

使用请求头方式：

{
  "mcpServers": {
    "moviepilot": {
      "url": "http://localhost:3001/api/v1/mcp",
      "headers": {
        "X-API-KEY": "your_api_key_here"
      }
    }
  }
}

或使用查询参数方式：

{
  "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/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/plugin/history/{plugin_id}

按需读取指定已安装插件的最新远端更新说明。该接口用于前端在用户点击“查看更新说明”时再实时访问插件仓库，避免加载已安装插件列表时批量请求网络。

1. 列出所有工具

GET /api/v1/mcp/tools

获取所有可用的MCP工具列表。

认证: 需要API KEY，在请求头中添加 X-API-KEY: <api_key> 或在查询参数中添加 apikey=<api_key>

响应示例:

[
  {
    "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>

请求体:

{
  "tool_name": "add_subscribe",
  "arguments": {
    "title": "流浪地球",
    "year": "2019",
    "media_type": "movie"
  }
}

响应示例:

{
  "success": true,
  "result": "成功添加订阅：流浪地球 (2019)",
  "error": null
}

错误响应示例:

{
  "success": false,
  "result": null,
  "error": "调用工具失败: 参数验证失败"
}

search_web 网络搜索示例:

{
  "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 路径范围。搜索默认使用系统代理配置。

3. 获取工具详情

GET /api/v1/mcp/tools/{tool_name}

获取指定工具的详细信息。

认证: 需要API KEY，在请求头中添加 X-API-KEY: <api_key> 或在查询参数中添加 apikey=<api_key>

路径参数:

• tool_name: 工具名称

响应示例:

{
  "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: 工具名称

响应示例:

{
  "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"]
}