Content
# MoviePilot MCP Server
[](https://opensource.org/licenses/MIT)
This is a **Model Context Protocol (MCP)** server implementation, designed to connect large language models (LLMs) with the [MoviePilot](https://github.com/jxxghp/MoviePilot) media library automation server.
## Goals
The goal of this project is to enable users to interact with their MoviePilot instance through natural language, allowing for:
* **Search and Discovery**: Search for movies, TV shows, and related information.
* **Query**: Query media details, season information, cast, and recommendations.
* **Find**: Find available download resources (torrent seeds).
* **Manage**: Manage media subscriptions (add, view, update, delete, enable/disable).
* **Control**: Control download tasks (add, view status, pause, resume, delete).
* **Get**: Get media library status (recently added, currently playing, check existence).
By exposing MoviePilot's functionality to LLMs, users can easily manage their media library through conversational interfaces supported by MCP, such as Cherry Studio or MCP-integrated clients.
## Usage
### 1. Running the MCP Server using Docker
This project supports deployment using Docker. You can pull a pre-built image from Docker Hub.
**Docker Hub Image:** `pollo3470/moviepilot-mcp`
#### a. Using `docker run`
1. **Pull the Image:**
```bash
docker pull pollo3470/moviepilot-mcp:latest
```
2. **Prepare `.env` File:**
Create a `.env` file in the directory where you want to run Docker, and fill in the necessary configuration information.
```dotenv
# .env
MOVIEPILOT_BASE_URL=http://your-moviepilot-ip:3000 # Your MoviePilot URL
MOVIEPILOT_USERNAME=your_moviepilot_username # Your MoviePilot username (for password authentication)
MOVIEPILOT_PASSWORD=your_moviepilot_password # Your MoviePilot password (for password authentication)
MCP_API_KEY=your_strong_api_key # Set a strong random API key to protect access to the MCP server. If not set, a random key will be generated and printed to the logs.
# Optional configurations
# LOG_LEVEL=INFO
```
3. **Run the Container:**
```bash
docker run -d \
--name moviepilot-mcp \
-p 8000:8000 \
--env-file ./.env \
--restart unless-stopped \
pollo3470/moviepilot-mcp:latest
```
Parameters:
* `-d`: Run the container in the background.
* `--name moviepilot-mcp`: Name the container.
* `-p 8000:8000`: Map port 8000 on the host to port 8000 in the container.
* `--env-file ./.env`: Load environment variables from the `.env` file in the current directory. You can also specify environment variables individually using multiple `-e` parameters, e.g.,
`-e MOVIEPILOT_BASE_URL="http://localhost:3000" -e MCP_API_KEY="your_secret_key"`.
* `--restart unless-stopped`: Automatically restart the container when it exits, unless manually stopped.
#### b. Using `docker-compose`
Refer to the `docker-compose.yml` file in the project's root directory to create a `docker-compose.yml` file.
1. **Prepare `.env` File:**
Create a `.env` file in the same directory as `docker-compose.yml`, and fill in the necessary configuration information as described above.
*Ensure `MCP_API_KEY` is set.*
2. **Run:**
```bash
docker-compose up -d
```
This command will pull the latest image (if local image does not exist or needs update) and start the service.
To stop the service, run:
```bash
docker-compose down
```
After starting, the MCP server will be available at `http://localhost:8000/mcp` (or the host and port you configured). Ensure that you include the `Authorization` header with your `MCP_API_KEY` in the `.env` file when making requests from the client.
### 2. Stdio Mode
Add the following configuration to an MCP-supported application (like Cline):
```json
{
"mcpServers": {
"moviepilot": {
"command": "uvx",
"args": [
"moviepilot-mcp"
],
"env": {
"MOVIEPILOT_BASE_URL": "URL of MoviePilot server",
"MOVIEPILOT_USERNAME": "Your MoviePilot username",
"MOVIEPILOT_PASSWORD": "Your MoviePilot password"
}
}
}
}
```
## Core Features
Based on MoviePilot's API, this MCP server plans to (or has) expose the following core features as MCP Tools:
### 1. Search and Discovery
* **Search Media:** Search for movies, TV shows, or persons by title/keywords.
* *MCP Tool:* `search_media_or_person`
* *Example:* "Search for the movie 'Interstellar'", "Find movies with actor 'Keanu Reeves'"
* **Explore:** Explore movies and TV shows from Douban, TMDB.
* *MCP Tool:* `discover_douban_media`, `discover_tmdb_media`
* *Example:* "Recommend some high-rated sci-fi movies on Douban", "Check out currently trending movies on TMDB"
* **Get New Releases:** Get upcoming movies or newly released TV shows from TMDB.
* *MCP Tool:* `get_upcoming_or_newly_released_media`
* *Example:* "What new movies are coming out?", "List recently aired TV shows"
### 2. Get Details
* **Media Details:** Query detailed information about a movie or episode (synopsis, ratings, IDs, etc.).
* *MCP Tool:* `get_media_details`
* *Example:* "Tell me detailed information about 'Dune 2'"
* **Season Information:** Query a TV show's season list or specific season's episode information.
* *MCP Tool:* `get_season_episodes`
* *Example:* "How many seasons does 'Friends' have?", "List episode titles for 'Stranger Things' Season 4"
### 3. Subscription Management
* **Add Subscription:** Add automatic download/monitoring for a movie or TV show.
* *MCP Tool:* `add_subscribe`
* *Example:* "Subscribe to the movie 'Dune 2'", "Subscribe to TV show 'Dark Honor' Season 1, excluding trailers"
* **List Subscriptions:** List all current subscriptions or details of a specific subscription.
* *MCP Tool:* `list_subscribes` (list all), `get_subscribe` (get one)
* *Example:* "What are my current subscriptions?", "Am I subscribed to 'Oppenheimer'?"
* **Update Subscription:** Modify an existing subscription's settings (e.g., filtering rules).
* *MCP Tool:* `update_subscribe`
* *Example:* "Change my 'The Last of Us' subscription to only download versions with special effects subtitles"
* **Delete Subscription:** Cancel a subscription.
* *MCP Tool:* `delete_subscribe`
* *Example:* "Cancel my subscription to 'Dune 2'"
* **Enable/Disable Subscription:** Pause or resume automatic searching for a subscription.
* *MCP Tool:* `set_subscribe_status`
* *Example:* "Pause the subscription with ID 3", "Enable the subscription with ID 3"
### 4. Resource Search
* **Precise Resource Search:** Search for downloadable torrents by TMDB ID or Douban ID.
* *API:* `GET /api/v1/search/media/{mediaid}`
* *Example:* "Find download resources for 'Oppenheimer'", "Search for torrents of 'The Last of Us' Season 1"
* **Fuzzy Resource Search:** Search for torrents by keywords.
* *API:* `GET /api/v1/search/title`
* *Example:* "Search for resources with '4K HDR Spider-Man' in the title"
### 5. Download Task Management
* **Add Download:** Download a specific torrent.
* *API:* `POST /api/v1/download/`
* *Example:* "Download the 'Oppenheimer' 4K torrent I found"
* **View Downloads:** List current ongoing download tasks.
* *API:* `GET /api/v1/download/`
* *Example:* "What are currently downloading? What's the progress?"
* **Control Download:** Pause, resume, or delete a download task.
* *API:* `GET /api/v1/download/stop/{hash}`, `GET /api/v1/download/start/{hash}`, `DELETE /api/v1/download/{hash}`
* *Example:* "Pause 'Dune 2' download", "Resume 'Oppenheimer' download", "Delete the failed download task"
### 6. Status and History Queries
* **Media Server Status:** View recently added or currently playing content on the media server.
* *API:* `GET /api/v1/mediaserver/latest`, `GET /api/v1/mediaserver/playing`
* *Example:* "What were recently added to my Jellyfin library?", "Is anyone currently watching a movie on Plex?"
* **Check Existence:** Query if a specific media exists in the library.
* *API:* `GET /api/v1/mediaserver/exists`
* *Example:* "Is 'Interstellar' in my library?", "Are all episodes of 'Friends' Season 1 available?"
* **Download History:** (Optional) View past download records.
* *API:* `GET /api/v1/history/download`
* *Example:* "What movies did I download last week?"
## Development Status
* Current Status: Gradually integrating MoviePilot features
* Future Plans: Provide MCP SSE deployment option
## Security Tips
* **Environment Security:** This server stores MoviePilot account credentials; ensure your environment is secure.
* **Account Security:** Consider creating a dedicated MoviePilot account for this MCP server to avoid using an admin account.
## Development Guide
**Prerequisites:**
* Python 3.12+
* uv package manager
* A running and accessible MoviePilot server instance
**Steps:**
1. **Clone Repository:**
```bash
git clone https://github.com/Pollo3470/MoviePilot-MCP
cd MoviePilot-MCP
```
2. **Configure:**
Create a `.env` file (can be copied from `.env.example`) and fill in necessary configurations:
```dotenv
# .env Example
MOVIEPILOT_BASE_URL=http://your-moviepilot-ip:3000 # Your MoviePilot URL
MOVIEPILOT_USERNAME=your_moviepilot_username # Your MoviePilot username (for password authentication)
MOVIEPILOT_PASSWORD=your_moviepilot_password # Your MoviePilot password (for password authentication)
MCP_API_KEY=your_strong_api_key # Set a strong random API key to protect access to the MCP server
```
3. **Create Environment:**
```bash
uv sync
```
## Contribution
Contributions are welcome! If you find bugs or have feature suggestions, submit an issue. If you want to contribute code, fork the repository and submit a pull request.
## Acknowledgments
Thanks to the [MoviePilot](https://github.com/jxxghp/MoviePilot) project. This project is built on top of MoviePilot's API, and without MoviePilot's excellent work, this MCP server would not be possible.
## License
This project is licensed under the [MIT License](LICENSE).
Connection Info
You Might Also Like
No recommendations available