# overseerr-mcp

MCP server for [Overseerr](https://overseerr.dev/) — 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

```bash
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`:

```yaml
mcp_servers:
  overseerr:
    url: "http://192.168.20.79:8053/mcp"
    timeout: 60
```

Or via CLI:

```bash
hermes config set mcp_servers.overseerr.url "http://192.168.20.79: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 | — |
| `HOST` | No | `0.0.0.0` |
| `PORT` | No | `8000` |

## API Key

Find it in Overseerr: **Settings → General → API Key**. Base64-encoded string, ~68 chars. The default user ("homelab" on David's instance) needs admin permissions to submit requests.

## Manual Run (for testing)

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