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

3. 会话管理

• 会话维持: 在标准 MCP 流程中，通过 HTTP Header MCP-Session-Id 识别会话。
• 主动终止: DELETE /api/v1/mcp (携带 MCP-Session-Id Header)

---

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	方法不存在
-32002	Session not found	会话不存在或已过期
-32003	Not initialized	会话未完成初始化流程
-32603	Internal error	服务器内部错误

6. RESTful API

所有工具相关的API端点都在 /api/v1/mcp 路径下（保持向后兼容）。

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": "电影"
  }
}

响应示例:

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

错误响应示例:

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

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

7. 注意事项

1. 用户上下文: API调用会使用当前认证用户的ID作为工具执行的用户上下文
2. 会话隔离: 每个API请求使用独立的会话ID
3. 参数验证: 工具参数会根据JSON Schema进行验证
4. 错误日志: 所有工具调用错误都会记录到MoviePilot日志系统