Content
# FastMCP server for Overseerr
FastMCP server to interact with the Overseerr API for movie and TV show requests management, built using the `fastmcp` library.
Project Repository: [https://github.com/ptbsare/overseerr-mcp-server](https://github.com/ptbsare/overseerr-mcp-server)
## Components
### Tools
The server implements the following tools to interact with Overseerr:
- `overseerr_status`: Get the status of the Overseerr server.
- `overseerr_movie_requests`: Get a paginated list of movie requests. Accepts optional `status`, `start_date` (YYYY-MM-DDTHH:MM:SS.mmmZ format), `take` (default 7), and `skip` (default 0).
- `overseerr_tv_requests`: Get a paginated list of TV show requests. Accepts optional `status`, `start_date` (YYYY-MM-DDTHH:MM:SS.mmmZ format), `take` (default 7), and `skip` (default 0).
- `overseerr_request_movie_to_library`: Submit a movie request using its TMDB ID to a specific library, on behalf of a specific user. Requires `tmdb_id`, `library_name`, and `user_display_name`. Available library names and user display names (unique ones only) are fetched at server startup and included in the tool's argument descriptions.
- `overseerr_request_tv_to_library`: Submit a TV show request using its TMDB ID to a specific library, on behalf of a specific user. Requires `tmdb_id`, `library_name`, and `user_display_name`. Optionally accepts `seasons` (list of integers). Available library names and user display names (unique ones only) are fetched at server startup and included in the tool's argument descriptions.
- `overseerr_search_media`: Search for movies and TV shows available on Overseerr. Accepts `query` and optional `page` (default 1).
- `overseerr_get_available_libraries`: Get the configured Sonarr (TV) and Radarr (Movie) server IDs and names from Overseerr.
- `overseerr_get_users`: Get a list of all users configured in Overseerr, including their ID, username, email, displayName, etc.
### Example prompts
It's good to first instruct your AI assistant (e.g., Claude) to use the Overseerr tools. Then it can call the appropriate tool when needed.
Try prompts like these:
- Get the status of our Overseerr server.
- Show me the first 5 movie requests that are currently pending.
- List all TV show requests from 2024-01-01 that are now available.
- What movies have been requested but are not available yet?
- What TV shows have recently become available in our library?
- Search for the movie "Dune: Part Two" on Overseerr.
- What movie and TV libraries are configured in Overseerr?
- List all users in Overseerr.
- Request the movie with TMDB ID 693134 for the user 'John Doe' in the 'Movies HD' library. (Uses `user_display_name='John Doe'`, `library_name='Movies HD'`)
- Request seasons 1 and 2 for the TV show with TMDB ID 1396 for user 'Jane Smith' in the 'TV Shows 4K' library. (Uses `user_display_name='Jane Smith'`)
## Quickstart
### Prerequisites
- `uv` (installation instructions: [https://github.com/astral-sh/uv](https://github.com/astral-sh/uv))
- An Overseerr instance running.
- API Key from your Overseerr instance (Settings → API Keys).
### Run with `uvx` (Recommended - No Installation Required)
You can run the server directly from the git repository using `uvx` — no clone or install needed:
```bash
uvx --from git+https://github.com/ptbsare/overseerr-mcp-server.git overseerr-mcp-server
```
### Claude Desktop Configuration
Add the following to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"overseerr-mcp-server": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/ptbsare/overseerr-mcp-server.git",
"overseerr-mcp-server"
],
"env": {
"OVERSEERR_API_KEY": "<your_api_key_here>",
"OVERSEERR_URL": "<your_overseerr_url>"
}
}
}
}
```
*Replace `<your_api_key_here>` and `<your_overseerr_url>` with your actual Overseerr API key and URL.*
### Environment Variables
The following environment variables are required:
- `OVERSEERR_API_KEY`: Your Overseerr API key (found in Overseerr Settings → API Keys)
- `OVERSEERR_URL`: The URL of your Overseerr instance (e.g., `http://localhost:5055`)
For clients like Claude Desktop, add these to the `env` field as shown above. For local use, you can export them or use a `.env` file:
```dotenv
OVERSEERR_API_KEY=your_api_key_here
OVERSEERR_URL=http://localhost:5055
```
### Local Development Installation
If you prefer to install locally for development:
```bash
git clone https://github.com/ptbsare/overseerr-mcp-server.git
cd overseerr-mcp-server
uv venv
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
uv pip install -e .
```
## Development
### Setup
Follow the installation steps using `uv pip install -e .` for an editable install.
### Dependencies
Install or sync dependencies using `uv`:
```bash
uv sync
# or
uv pip install -e .
```
### Debugging
Since MCP servers run over stdio, debugging can be challenging.
- **MCP Inspector:** The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is highly recommended.
Launch it pointing to your server script:
```bash
# Using uvx (no local installation needed)
npx @modelcontextprotocol/inspector uvx --from git+https://github.com/ptbsare/overseerr-mcp-server.git overseerr-mcp-server
# Or using uv run (from local project directory)
npx @modelcontextprotocol/inspector uv run overseerr-mcp-server
```
Access the URL provided by the Inspector in your browser.
- **Logging:** The server logs basic information to stdout/stderr. Check the terminal where you ran `uv run overseerr-mcp-server`. For clients like Claude Desktop, check the client's log files (e.g., `~/Library/Logs/Claude/mcp-server-overseerr-mcp.log` on macOS, but the name might vary based on your config).
## License
MIT
