overseerr-mcp

MCP server for Overseerr — search, request, and manage media from Hermes Agent.

Tools

Tool	Description
search	Search movies & TV shows (returns TMDB IDs + availability)
get_movie	Full movie details by TMDB ID
get_tv	Full TV show details (seasons, episodes)
request_media	Submit a request → triggers Radarr/Sonarr pipeline
pending_requests	List all pending/processing requests
server_status	Overseerr version + connection health

Quick Start

cp .env.example .env
# Edit .env with your Overseerr URL and API key
docker compose up -d

The server exposes an MCP SSE endpoint at http://localhost:8000/sse.

Connect from Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  overseerr:
    url: "http://<your-host>:8053/mcp"
    timeout: 60

Or via CLI:

hermes config set mcp_servers.overseerr.url "http://<your-host>:8053/mcp"
hermes config set mcp_servers.overseerr.timeout 60

Then restart Hermes. Tools appear as mcp_overseerr_search, mcp_overseerr_request_media, etc.

Portainer Stack

Paste the contents of docker-compose.yml into Portainer Stacks, or point Portainer at this repo. Create a .env file with your OVERSEERR_API_KEY.

Environment Variables

Variable	Required	Default
OVERSEERR_URL	Yes	—
OVERSEERR_API_KEY	Yes	—
MCP_ALLOWED_HOST	No	localhost:*
HOST	No	0.0.0.0
PORT	No	8000

API Key

Find it in Overseerr: Settings → General → API Key. Base64-encoded string, ~68 chars. An admin user (Owner role in Overseerr) needs permissions to submit requests.

Manual Run (for testing)

pip install -r requirements.txt
OVERSEERR_URL=http://your-overseerr-host:5055 \
OVERSEERR_API_KEY=your-api-key-here \
python server.py