/moviepilot-api
Use this skill when you need to call MoviePilot REST API endpoints directly with the bundled Python client. Covers MoviePilot HTTP endpoints across media search, downloads, subscriptions, library management, site management, system administration, plugins, workflows, and more.
$ npx -y skills add jxxghp/moviepilot --skill moviepilot-api --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/moviepilot-api
Context preview
The summary Claude sees to decide when to auto-load this skill.
Use this skill when you need to call MoviePilot REST API endpoints directly with the bundled Python client. Covers MoviePilot HTTP endpoints across media search, downloads, subscriptions, library management, site management, system administration, plugins, workflows, and more.
SKILL.md
moviepilot-api.SKILL.mdname: moviepilot-api
version: 11
description: >-
Use this skill when you need to call MoviePilot REST API endpoints directly
with the bundled Python client. Covers MoviePilot HTTP endpoints across media
search, downloads, subscriptions, library management, site management, system
administration, plugins, workflows, and more. Prefer `moviepilot-cli` for
normal local MCP tool workflows; use this skill when the user explicitly asks
for HTTP API access, when an endpoint is not exposed as an MCP tool, or when
running in an environment where direct REST calls are the appropriate bridge.
MoviePilot REST API
> All script paths are relative to this skill file.
Use `scripts/mp-api.py` to call any MoviePilot REST API endpoint directly.
Scope And Boundaries
This skill is the REST API bridge. It is implemented as a Python script and is useful when the agent needs endpoint-level coverage beyond the local `moviepilot tool` MCP CLI.
Choose other skills first when they match more precisely:
| Request | Preferred skill | |---|---| | Normal local MoviePilot product operation exposed as an MCP tool | `moviepilot-cli` | | Direct SQL query or database update | `database-operation` | | Restart, version check, or upgrade | `moviepilot-update` | | Slash commands or plugin/system command dispatch | `command-dispatch` | | Browser-only state, site login pages, screenshots, cookies | `browser-use` |
Do not use this skill just because MoviePilot is mentioned. Use it when the task specifically needs a REST endpoint, token-query endpoint, or API behavior that the CLI/MCP tools do not expose.
Setup
When the script runs inside the MoviePilot project, it imports `app.core.config.settings` and reads `settings.HOST`, `settings.PORT`, and `settings.API_TOKEN` directly. Do not ask the user for `API_TOKEN`, and do not copy API keys into the prompt.
Configuration priority:
1. CLI flags: `--host`, `--apikey` 2. Environment variables: `MP_HOST`, `MP_API_KEY` 3. Local MoviePilot settings 4. Legacy config file: `~/.config/moviepilot_api/config`
Use `configure` only as a legacy fallback outside the MoviePilot project, and avoid it in normal agent workflows because it persists a long-lived API key to disk.
How to Call APIs
General syntax
python scripts/mp-api.py <METHOD> <PATH> [key=value ...] [--json '<body>']
Authentication
- By default, the script auto-loads the local key and sends it via the `X-API-KEY` header.
- For endpoints suffixed with `2` (e.g. `/api/v1/dashboard/statistic2`), use `--token-param` to send the key as `?token=`.
- Both methods validate against the same `API_TOKEN` value.
- Never print, summarize, or ask the user to paste the API key unless the script is being used outside the local project and no safer configuration source is available.
API versions and response envelopes
- `/api/v1` preserves the existing endpoint-specific response shapes by
default; the login wallpaper URL is now returned in `data`.
- `/api/v2` reuses the same routes, parameters, authentication dependencies,
and business handlers, but wraps ordinary JSON responses in the shared `Response` envelope.
- A successful raw v1 payload becomes
`{"success":true,"message":"","data":<original payload>}` in v2.
- Existing `Response` payloads are not wrapped again. HTTP errors on both v1
and v2 keep their original status code and expose the error text in `message` with `data={}`. Non-business HTTP exceptions are not translated.
- SSE, files, images, empty responses, and OpenAI, Anthropic, or MCP protocol
endpoints keep their protocol-native response body.
Use `/api/v2` for app clients that require one JSON envelope. Any ordinary REST path listed below can switch from `/api/v1/...` to `/api/v2/...` without changing its method, parameters, request body, or authentication.
Examples
# GET with query params
python scripts/mp-api.py GET /api/v1/media/search title="Avatar" type="movie"
# POST with JSON body
python scripts/mp-api.py POST /api/v1/download/add --json '{"torrent_url":"abc1234:1"}'
# DELETE
python scripts/mp-api.py DELETE /api/v1/subscribe/123
# Endpoints that require ?token= auth
python scripts/mp-api.py GET /api/v1/dashboard/statistic2 --token-param
# Uniform v2 JSON response envelope
python scripts/mp-api.py GET /api/v2/dashboard/cpuComplete API Reference
All endpoints are under the base URL `{MP_HOST}`. Path parameters are shown as `{param}`.
---
Media Search (13 endpoints)
| Method | Path | Description | |--------|------|-------------| | GET | `/api/v1/media/search` | Search media, collections, or people by title. Params: `title` (required), `type`, `page`, `count`, optional `source`. Supported sources: `media` = `themoviedb`, `douban`, `bangumi`, `anilist`; `collection` = `themoviedb`; `person` = `themoviedb`, `douban` | | GET | `/api/v1/media/recognize` | Recognize media from a torrent title or a media file path. Params: `title` (required), `subtitle`, `custom_words`, optional `source`; media file paths also use parent-directory metadata such as title and year | | GET | `/api/v1/media/recognize2` | Recognize media from a torrent title or media file path (API_TOKEN auth, use `--token-param`). Params: `title`, `subtitle`, `custom_words`, optional `source`; media file paths also use parent-directory metadata | | GET | `/api/v1/media/recognize_file` | Recognize media from file path. Params: `path` (required), optional `source` | | GET | `/api/v1/media/recognize_file2` | Recognize file (API_TOKEN auth). Params: `path`, optional `source` | | POST | `/api/v1/media/scrape/{storage}` | Scrape media metadata. Body: FileItem JSON. Optional params: `media_source`, `media_id`, `type_name` (`电影`/`电视剧`) | | GET | `/api/v1/media/category/config` | Get category strategy config | | POST | `/api/v1/media/category/config` | Save category strategy config. Body: CategoryConfig | | GET | `/api/v1/media/category` | Get auto-categorization config
Read more
name: moviepilot-api version: 11 description: >- Use this skill when you need to call MoviePilot REST API endpoints directly with the bundled Python client. Covers MoviePilot HTTP endpoints across media search, downloads, subscriptions, library management, site management, system administration, plugins, workflows, and more. Prefer `moviepilot-cli` for normal local MCP tool workflows; use this skill when the user explicitly asks for HTTP API access, when an endpoint is not exposed as an MCP tool, or when running in an environment where direct REST calls are the appropriate bridge.
MoviePilot REST API
> All script paths are relative to this skill file.
Use `scripts/mp-api.py` to call any MoviePilot REST API endpoint directly.
Scope And Boundaries
This skill is the REST API bridge. It is implemented as a Python script and is useful when the agent needs endpoint-level coverage beyond the local `moviepilot tool` MCP CLI.
Choose other skills first when they match more precisely:
| Request | Preferred skill | |---|---| | Normal local MoviePilot product operation exposed as an MCP tool | `moviepilot-cli` | | Direct SQL query or database update | `database-operation` | | Restart, version check, or upgrade | `moviepilot-update` | | Slash commands or plugin/system command dispatch | `command-dispatch` | | Browser-only state, site login pages, screenshots, cookies | `browser-use` |
Do not use this skill just because MoviePilot is mentioned. Use it when the task specifically needs a REST endpoint, token-query endpoint, or API behavior that the CLI/MCP tools do not expose.
Setup
When the script runs inside the MoviePilot project, it imports `app.core.config.settings` and reads `settings.HOST`, `settings.PORT`, and `settings.API_TOKEN` directly. Do not ask the user for `API_TOKEN`, and do not copy API keys into the prompt.
Configuration priority:
1. CLI flags: `--host`, `--apikey` 2. Environment variables: `MP_HOST`, `MP_API_KEY` 3. Local MoviePilot settings 4. Legacy config file: `~/.config/moviepilot_api/config`
Use `configure` only as a legacy fallback outside the MoviePilot project, and avoid it in normal agent workflows because it persists a long-lived API key to disk.
How to Call APIs
General syntax
python scripts/mp-api.py <METHOD> <PATH> [key=value ...] [--json '<body>']
Authentication
- By default, the script auto-loads the local key and sends it via the `X-API-KEY` header.
- For endpoints suffixed with `2` (e.g. `/api/v1/dashboard/statistic2`), use `--token-param` to send the key as `?token=`.
- Both methods validate against the same `API_TOKEN` value.
- Never print, summarize, or ask the user to paste the API key unless the script is being used outside the local project and no safer configuration source is available.
API versions and response envelopes
- `/api/v1` preserves the existing endpoint-specific response shapes by
default; the login wallpaper URL is now returned in `data`.
- `/api/v2` reuses the same routes, parameters, authentication dependencies,
and business handlers, but wraps ordinary JSON responses in the shared `Response` envelope.
- A successful raw v1 payload becomes
`{"success":true,"message":"","data":<original payload>}` in v2.
- Existing `Response` payloads are not wrapped again. HTTP errors on both v1
and v2 keep their original status code and expose the error text in `message` with `data={}`. Non-business HTTP exceptions are not translated.
- SSE, files, images, empty responses, and OpenAI, Anthropic, or MCP protocol
endpoints keep their protocol-native response body.
Use `/api/v2` for app clients that require one JSON envelope. Any ordinary REST path listed below can switch from `/api/v1/...` to `/api/v2/...` without changing its method, parameters, request body, or authentication.
Examples
# GET with query params
python scripts/mp-api.py GET /api/v1/media/search title="Avatar" type="movie"
# POST with JSON body
python scripts/mp-api.py POST /api/v1/download/add --json '{"torrent_url":"abc1234:1"}'
# DELETE
python scripts/mp-api.py DELETE /api/v1/subscribe/123
# Endpoints that require ?token= auth
python scripts/mp-api.py GET /api/v1/dashboard/statistic2 --token-param
# Uniform v2 JSON response envelope
python scripts/mp-api.py GET /api/v2/dashboard/cpuComplete API Reference
All endpoints are under the base URL `{MP_HOST}`. Path parameters are shown as `{param}`.
---
Media Search (13 endpoints)
| Method | Path | Description | |--------|------|-------------| | GET | `/api/v1/media/search` | Search media, collections, or people by title. Params: `title` (required), `type`, `page`, `count`, optional `source`. Supported sources: `media` = `themoviedb`, `douban`, `bangumi`, `anilist`; `collection` = `themoviedb`; `person` = `themoviedb`, `douban` | | GET | `/api/v1/media/recognize` | Recognize media from a torrent title or a media file path. Params: `title` (required), `subtitle`, `custom_words`, optional `source`; media file paths also use parent-directory metadata such as title and year | | GET | `/api/v1/media/recognize2` | Recognize media from a torrent title or media file path (API_TOKEN auth, use `--token-param`). Params: `title`, `subtitle`, `custom_words`, optional `source`; media file paths also use parent-directory metadata | | GET | `/api/v1/media/recognize_file` | Recognize media from file path. Params: `path` (required), optional `source` | | GET | `/api/v1/media/recognize_file2` | Recognize file (API_TOKEN auth). Params: `path`, optional `source` | | POST | `/api/v1/media/scrape/{storage}` | Scrape media metadata. Body: FileItem JSON. Optional params: `media_source`, `media_id`, `type_name` (`电影`/`电视剧`) | | GET | `/api/v1/media/category/config` | Get category strategy config | | POST | `/api/v1/media/category/config` | Save category strategy config. Body: CategoryConfig | | GET | `/api/v1/media/category` | Get auto-categorization config
Repo: jxxghp/moviepilot
Other skills on moviepilot.
- /anysearch
API key for higher rate limits. Anonymous access available with lower rate limits.
Open skill - /browser-use
Use this skill when the user asks the agent to open, browse, inspect, extract content from, click through, fill forms on, screenshot, or verify a web page with a browser. Also use it for MoviePilot scenarios that need browser interaction, such as checking a site page, confirming
Open skill - /command-dispatch
Use this skill when the user's intent is to execute a system or plugin function. Applicable scenarios include: 1) The user sends a slash command starting with / (e.g. /cookiecloud, /sites, /subscribes, etc.); 2) The user describes an action in natural language that can be
Open skill - /create-moviepilot-plugin
Use this skill when the user asks to create, modify, debug, validate, or scaffold a MoviePilot local plugin. Covers MoviePilot V2 plugin development, _PluginBase implementations, package.v2.json/package.json market metadata, plugins.v2/plugins source layout,
Open skill - /create-moviepilot-skill
Use this skill when the user asks to create, scaffold, update, or review a MoviePilot agent skill. This includes adding a new built-in skill under the repository `skills/` directory, editing an existing built-in skill, writing `SKILL.md` frontmatter and workflow instructions,
Open skill - /database-operation
Use this skill when you need to inspect, query, maintain, or carefully modify the MoviePilot database. This skill uses the bundled scripts/mp-db.py helper, which reads MoviePilot local settings itself and never requires database passwords or full PostgreSQL DSNs in the agent
Open skill