# MoviePilot MCP Admin

> MoviePilot MCP 服务管理插件 - 让 AI Agent 通过 MCP 协议控制 MoviePilot

## 功能特性

- 🔌 **MCP 协议支持**: 实现标准 Model Context Protocol，让 AI Agent 可以调用 MoviePilot 功能
- 📺 **订阅管理**: 通过自然语言添加、删除、查看订阅
- ⬇️ **下载控制**: 暂停、恢复、删除下载任务
- 🔍 **媒体搜索**: 搜索电影、电视剧信息
- 📊 **系统状态**: 查看系统运行状态和日志

## 支持的 MCP 工具

### 订阅管理
| 工具 | 描述 |
|------|------|
| `subscribe_list` | 列出所有订阅 |
| `subscribe_add` | 添加订阅 |
| `subscribe_delete` | 删除订阅 |

### 下载管理
| 工具 | 描述 |
|------|------|
| `download_list` | 列出下载任务 |
| `download_pause` | 暂停下载 |
| `download_resume` | 恢复下载 |
| `download_delete` | 删除下载 |

### 媒体搜索
| 工具 | 描述 |
|------|------|
| `media_search` | 搜索媒体信息 |
| `media_details` | 获取媒体详情 |
| `media_exists` | 检查媒体是否存在 |

### 系统管理
| 工具 | 描述 |
|------|------|
| `system_status` | 获取系统状态 |
| `system_restart` | 重启服务 |
| `system_logs` | 获取日志 |

## 安装

### 方法 1: 插件市场

在 MoviePilot 插件市场中添加仓库地址：

```
https://github.com/q2a3z4w/moviepilot-mcp-admin
```

### 方法 2: 手动安装

1. 克隆仓库到 `app/plugins/moviepilot_mcp_admin` 目录
2. 重启 MoviePilot

## 配置

1. 在 MoviePilot 设置中找到「MCP服务管理」
2. 启用 MCP 服务
3. 复制生成的 API Key（用于 AI Agent 认证）

## AI Agent 配置

### Claude Desktop

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

### OpenClaw

使用 `mcporter` 工具添加 MoviePilot MCP 服务。

## API 端点

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/v1/mcp` | MCP JSON-RPC 端点 |
| GET | `/api/v1/mcp/tools` | 列出所有工具 |
| GET | `/api/v1/mcp/tools/{name}` | 获取工具详情 |

## 使用示例

### 自然语言订阅

```
用户: "帮我订阅电视剧《黑暗荣耀》第二季"
AI: 调用 subscribe_add(title="黑暗荣耀", year="2024", media_type="电视剧", season=2)
```

### 查询下载状态

```
用户: "现在有哪些任务在下载？"
AI: 调用 download_list(status="active")
```

## 开发

```bash
# 克隆项目
git clone https://github.com/q2a3z4w/moviepilot-mcp-admin

# 安装依赖（如需要）
pip install -r requirements.txt

# 复制到 MoviePilot 插件目录
cp -r app/plugins/moviepilot_mcp_admin <moviepilot>/app/plugins/
```

## 技术栈

- Python 3.12+
- FastAPI
- MoviePilot Plugin Framework V2
- JSON-RPC 2.0

## License

MIT