Content
# MediaStack MCP
A unified [Model Context Protocol](https://modelcontextprotocol.io/) server for home media stacks. Polls 13 services, records events/storage/health to PostgreSQL, and exposes tools for AI agents to observe and act on your media library.
## What it does
**Observer** — Continuously polls your media services and builds institutional memory:
- What was grabbed, imported, failed, upgraded, downloaded
- Storage usage with growth forecasting
- Library sizes across all services
- Service health with degradation detection
**Actor** — Controlled content management with a two-step confirmation protocol:
- Search and add content to Sonarr/Radarr/Lidarr
- Remove content from Sonarr/Radarr/Lidarr (with optional file deletion)
- Request or cancel content via Seerr
- Trigger missing episode/movie searches
- Trigger subtitle searches via Bazarr
Every write operation requires explicit confirmation before execution. Destructive operations (file deletion) use a shortened 2-minute confirmation expiry with prominent warnings.
## Supported Services
| Service | Events | Libraries | Health | Write |
|---|---|---|---|---|
| Sonarr | history | series + size | warnings | add, delete, search |
| Radarr | history | movies + size | warnings | add, delete, search |
| Lidarr | history | artists + size | warnings | add, delete, search |
| Prowlarr | — | — | warnings | — |
| Bazarr | subtitle history | — | warnings | subtitle search |
| Jellyfin | — | per-library counts | ping | favourite, watched, collections, playlists |
| Seerr | request pipeline | — | ping | request, cancel |
| Audiobookshelf | — | books + podcasts | ping | — |
| Boxarr | scheduler runs | — | ping | — |
| Suggestarr | recommendation stats | — | ping | — |
| Dispatcharr | — | IPTV channels | ping | — |
| SABnzbd | download history | — | ping | — |
| qBittorrent | state diff | — | ping | — |
Services are auto-discovered from environment variables. Missing services are silently skipped.
## MCP Tools (27)
### Read
- `mediastack_timeline` — Recent events from all sources
- `mediastack_storage` — Disk usage with growth forecasts
- `mediastack_health` — Service health status
- `mediastack_search` — Search events by title
- `mediastack_stats` — Database statistics
- `mediastack_libraries` — Library sizes and deltas
- `mediastack_summary` — Condensed digest (daily/weekly/monthly)
### Write (confirmation required)
- `mediastack_search_content` — Search *arr lookup APIs
- `mediastack_add_content` — Add to Sonarr/Radarr/Lidarr
- `mediastack_list_profiles` — Show quality profiles and root folders
- `mediastack_request_content` — Request via Seerr
- `mediastack_search_missing` — Trigger missing content search
- `mediastack_search_subtitles` — Trigger Bazarr subtitle search
- `mediastack_delete_content` — Remove from Sonarr/Radarr/Lidarr (optional file deletion)
- `mediastack_cancel_request` — Cancel a Seerr request
- `mediastack_confirm` — Execute a previewed write action
### Jellyfin
- `mediastack_jellyfin_search` — Search Jellyfin library by name
- `mediastack_jellyfin_genres` — List genres or browse items by genre
- `mediastack_jellyfin_favorites` — List a user's favourites (optional `user_name`)
- `mediastack_jellyfin_collections` — List collections or items in a collection
- `mediastack_jellyfin_playlists` — List playlists or items in a playlist
- `mediastack_jellyfin_favorite` — Add/remove item from favourites
- `mediastack_jellyfin_watched` — Mark item as played/unplayed
- `mediastack_jellyfin_collection_create` — Create a new collection
- `mediastack_jellyfin_collection_modify` — Add/remove items from a collection
- `mediastack_jellyfin_playlist_create` — Create a new playlist
- `mediastack_jellyfin_playlist_modify` — Add/remove/reorder playlist items
## Quick Start
### Prerequisites
- Docker and Docker Compose
- PostgreSQL (for event/storage/health data)
- At least one *arr service running
### 1. Create the database
```bash
docker exec postgres psql -U postgres \
-c "CREATE USER mediastack WITH PASSWORD 'your_password';" \
-c "CREATE DATABASE mediastack OWNER mediastack;"
```
### 2. Configure environment
```bash
cd mediastack-mcp
cp .env.example .env # or symlink to your shared env file
```
Required variables:
```env
# Database
DB_MEDIASTACK_NAME=mediastack
DB_MEDIASTACK_USER=mediastack
DB_MEDIASTACK_PASS=your_password
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
# Add services (only configured services are polled)
SONARR_URL=http://sonarr:8989
SONARR_API_KEY=your_key
RADARR_URL=http://radarr:7878
RADARR_API_KEY=your_key
# ... etc
```
### 3. Build and run
```bash
docker compose build
docker compose up -d
```
### 4. Verify
```bash
curl http://127.0.0.1:9202/health
```
```json
{
"status": "ok",
"events": 202,
"sources": 5,
"services": "Active services: radarr, sabnzbd, sonarr, ..."
}
```
## Authentication (optional)
Set `MEDIASTACK_AUTH_TOKEN` to require a bearer token on `/mcp` and `/ingest`
(401 without it). `/health` stays open for the Docker healthcheck. When the
variable is unset, everything behaves as before — existing deployments are
unaffected until they opt in.
```bash
# generate a token
openssl rand -hex 32
```
Host port binding to 127.0.0.1 protects against the LAN, but not against
other containers sharing the Docker network. The token closes that gap.
## Connecting to MCP Clients
### Claude Code
Add to `.mcp.json`:
```json
{
"mcpServers": {
"mediastack": {
"type": "stdio",
"command": "npx",
"args": ["mcp-remote", "http://127.0.0.1:9202/mcp"]
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"mediastack": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://your-host:9202/mcp"]
}
}
}
```
For non-HTTPS connections, add `"--allow-http"` to the args.
With `MEDIASTACK_AUTH_TOKEN` set, pass the token via `mcp-remote`'s
`--header` flag (one array element for the flag, one for the value):
```json
"args": [
"mcp-remote", "http://127.0.0.1:9202/mcp",
"--header", "Authorization: Bearer your_token_here"
]
```
## Architecture
```
app/
├── server.py # FastMCP server, 27 tools, /health endpoint
├── config.py # Service auto-discovery from env vars
├── db.py # PostgreSQL schema + queries
├── poller.py # Background polling engine
├── confirmations.py # Write confirmation protocol (5-min standard, 2-min for file deletion)
├── retention.py # Data rollup (90d events, 14d storage)
└── clients/ # Per-service API clients (13 services)
```
- **Transport:** Streamable HTTP (FastMCP)
- **Database:** PostgreSQL with JSONB metadata
- **Polling:** Asyncio polling loops running in a dedicated daemon thread (own event loop), with configurable intervals
- **Deduplication:** Events keyed by `source_event_id` (unique constraint)
- **Health:** Sparse table — only records state changes
- **Retention:** Events rolled up to daily summaries after 90 days; storage snapshots rolled up to daily averages after 14 days
## Configuration Reference
### Polling Intervals
| Variable | Default | Description |
|---|---|---|
| `MEDIASTACK_POLL_INTERVAL` | 300 | Event polling interval (seconds) |
| `MEDIASTACK_STORAGE_INTERVAL` | 3600 | Storage snapshot interval (seconds) |
| `MEDIASTACK_LIBRARY_INTERVAL` | 21600 | Library snapshot interval (seconds) |
| `MEDIASTACK_AUTH_TOKEN` | unset | Bearer token required on `/mcp` and `/ingest` when set |
### Service Environment Variables
<details>
<summary>API Key services (URL + key)</summary>
| Service | URL | Key |
|---|---|---|
| Sonarr | `SONARR_URL` | `SONARR_API_KEY` |
| Radarr | `RADARR_URL` | `RADARR_API_KEY` |
| Lidarr | `LIDARR_URL` | `LIDARR_API_KEY` |
| Prowlarr | `PROWLARR_URL` | `PROWLARR_API_KEY` |
| Bazarr | `BAZARR_URL` | `BAZARR_API_KEY` |
| Jellyfin | `JELLYFIN_URL` | `JELLYFIN_API_KEY` |
| Seerr | `SEERR_URL` | `SEERR_API_KEY` |
| Audiobookshelf | `AUDIOBOOKSHELF_URL` | `AUDIOBOOKSHELF_API_KEY` |
</details>
<details>
<summary>Credential services (URL + username + password)</summary>
| Service | URL | Username | Password |
|---|---|---|---|
| qBittorrent | `QBITTORRENT_URL` | `QBITTORRENT_USERNAME` | `QBITTORRENT_PASSWORD` |
| Dispatcharr | `DISPATCHARR_URL` | `DISPATCHARR_USERNAME` | `DISPATCHARR_PASSWORD` |
| Suggestarr | `SUGGESTARR_URL` | `SUGGESTARR_USERNAME` | `SUGGESTARR_PASSWORD` |
</details>
<details>
<summary>Other</summary>
| Service | URL | Auth |
|---|---|---|
| SABnzbd | `SABNZBD_URL` | `SABNZBD_API_KEY` |
| Boxarr | `BOXARR_URL` | None |
</details>
## Tech Stack
- Python 3.14
- [FastMCP](https://github.com/jlowin/fastmcp) (MCP SDK)
- PostgreSQL (psycopg2)
- httpx (async HTTP client)
- Uvicorn + Starlette
## Testing
Four tiers — tiers 1–3 run anywhere (laptop, CI) with no media services
and no credentials:
```bash
pip install -r requirements.txt -r requirements-dev.txt
pytest # tiers 1–3
pytest -m live # tier 4 (manual, opt-in)
```
1. **Pure logic** — confirmation protocol (expiry, renewal,
execute-exactly-once), scan path validation, env auto-discovery,
auth middleware
2. **Mocked HTTP** (respx, recorded fixtures) — delete previews,
client auth headers, *arr history parsing and dedup IDs
3. **Real PostgreSQL** — schema idempotency, event dedup, retention
rollup, storage growth. Uses `TEST_DATABASE_URL` if set (CI), else
a throwaway [testcontainers](https://testcontainers-python.readthedocs.io/)
instance
4. **Live smoke** (`pytest -m live`) — read-only checks against a
running deployment; never exercises write or confirm tools
## How this was built
This project was designed and implemented entirely using [Claude](https://claude.ai) (Anthropic's AI assistant), working from a detailed requirements specification. The spec covered architecture, service integration, database schema, polling strategy, MCP tool design, and a phased delivery plan. Claude wrote all the code, documentation, and Docker configuration across five implementation phases.
The human contribution was the product vision, requirements, and iterative feedback — Claude handled the engineering.
## License
[MIT](LICENSE)