ArrPi connects your media services through a cached API, CLI and MCP server, with an optional web UI. Build a dashboard, follow upcoming releases or let an AI assistant search your library and request media.
- Dashboards: library, queue and monitoring summaries, with per-source freshness and failures. Give each client a scoped key instead of sharing your apps’ API keys.
- Calendar: movie releases and TV episodes together, with search, filters and personal RSS/iCalendar feeds.
- AI assistants: search, recommendations, requests, issues and batch tools through MCP. Refresh installed media or search for missing episodes without adding it again. Requests act as each account's Seerr user.
- Scripts: a JSON CLI for automation and agents.
Calendar
| Source overview | MCP connections and usage |
|---|---|
 |
 |
Screenshots use fictional media.
Claude Code compares community ratings, checks upcoming releases, makes batch requests with a chosen profile and searches for missing episodes. All media in the recording is fictional.
mcp-demo.mp4
You need Docker with Compose v2 and at least one supported service: Sonarr v4, Radarr (v3 API), Seerr, SABnzbd, Bazarr, Cleanuparr, Maintainerr, Plex or CrossWatch.
git clone https://github.com/legacy3/arrpi.git
cd arrpi
docker compose -f deploy/compose.yaml up --no-build --pull always -d --wait
docker compose -f deploy/compose.yaml exec arrpi config keyThe API listens on 127.0.0.1:8780. config key prints the admin key for setup.
Add the optional frontend:
docker compose -f deploy/compose.yaml -f deploy/compose.web.yaml up --no-build --pull always -d --waitBoth ports bind to loopback. For remote access, use a TLS reverse proxy; see routing and SSO.
| Image | Contains |
|---|---|
ghcr.io/legacy3/arrpi-core |
API, CLI, MCP server and SQLite state |
ghcr.io/legacy3/arrpi-ui |
Optional web frontend; no database mount |
Both images run non-root with read-only filesystems on Linux amd64 and arm64. Builds from main that pass CI publish latest and sha-<full commit> tags. Pin matching commit tags or digests when deploying the pair.
The UI reads ARRPI_CORE_ORIGIN at startup, so changing its core server does not require a rebuild.
Open http://127.0.0.1:3000/ and enter the admin key. Add your apps’ URLs and API keys under Settings → Connections. ArrPi must be able to reach those URLs; for apps in Docker, use their service names on a shared network.
Create client keys under Settings → Access. Choose Media assistant for MCP, Read only for browsing, API reader for scripts or Administrator for server setup. Presets use your configured sources; expand Customize permissions for individual grants. Keep the admin key separate from requester accounts.
The overview puts current connection health before library, queue and app activity. Diagnostics stay collapsible. In Explorer, choose a source to see its available reads and account commands. Common commands offer title lookup and guided fields, with JSON available for advanced use. All sources groups combined library, queue, monitoring and calendar operations. Seerr searches, requests and issues use the connected requester account. The calendar combines the connected Sonarr and Radarr libraries. Personal RSS/iCalendar setup is covered in feeds.
Set ARRPI_URL and ARRPI_API_KEY to your ArrPi server and client key, or use --url and --key-env.
# Read a library or download queue
arrpi get sonarr series --pretty
arrpi get radarr queue --page 1 --page-size 20 --no-cache --metadata
# Combine movie and episode releases
arrpi calendar --start 2026-10-01 --end 2026-10-31
# Find an available comedy
arrpi tool search_library --arguments '{"genres":["Comedy"],"available":true,"min_rating":7,"rating_provider":"imdb","min_votes":10000}'
# Check ArrPi or discover native apps
arrpi health
arrpi discover --ip 192.0.2.10Output is JSON; failures return a nonzero exit code. Run arrpi --help for arguments.
For fresh data, use --no-cache, the web UI’s Explorer → Fresh upstream read checkbox or an MCP tool’s no_cache argument.
Download binaries and SHA-256 checksums from Releases: Linux x86-64/ARM64, macOS Intel/Apple Silicon and Windows x86-64. The executable includes the API, CLI and MCP server; Docker is optional. See Linux/macOS setup or Windows setup.
Use cargo run --locked -p arrpi -- <command>. Rust 1.95 or newer is supported; the repository pins 1.96.1.
cargo run --locked -p arrpi -- serve --database .arrpi/arrpi.sqlite
# In another terminal:
cargo run --locked -p arrpi -- config key --database .arrpi/arrpi.sqliteRequests and issues support stable Seerr >=3.5.0, <4.0.0 releases and require Plex-bound Seerr users. Local, Jellyfin and Emby requester accounts are not supported yet. Native library, maintenance and optional original-file download links use separate source grants. See MCP tools.
- Add Seerr and bind each ArrPi account to its Seerr user in Settings.
- Enable the server under Settings → MCP. Tool switches and limits are here too.
- Open MCP and copy the install command for Claude Code, Codex or Gemini CLI. Each account gets its own token.
The MCP page shows searchable write history, command progress, effective tool access and usage. Name your stack in Settings → General; the UI, feeds and MCP share that identity. Set the catalog language in the Seerr connection settings; it defaults to English (en).
Requests retain Seerr’s permissions, quotas, profiles, approval rules and requester tags. ArrPi never requests 4K or deletes library media. Optional connections to SABnzbd, Cleanuparr, Bazarr and Maintainerr expose read-only counters with their own access grants.
HTTP clients use /v1/mcp; stdio clients use arrpi mcp --url https://arrpi.example.com. MCP and media requests documents setup, tools, profiles, pagination and uncertain outcomes.
The CrossWatch adapter lets portals connect each person’s Plex account to multiple playback destinations and control tracking per service through an account-bound API. CrossWatch handles authorization and playback; no bulk history import is started.
Settings, credentials, account tokens, feed subscriptions, usage and write history live in /state/arrpi.sqlite. Schema migrations run automatically.
Stop core before copying the database and save the deployed image digests so you can restore the same version. Restore the database with UID 1000 ownership and mode 0600. The UI, cache and build output are disposable. See configuration and operations for details.
| Document | Contents |
|---|---|
| HTTP API and feeds | Native reads, calendars, RSS/iCalendar, permissions and personal subscriptions |
| MCP and media requests | Account setup, tools, requests/profiles, errors, statistics and history |
| Configuration and operations | Settings, container routing, SSO, recovery and limits |
| External OAuth | MCP resource discovery, compatible issuers and explicit account bindings |
| Architecture | Crate boundaries, source capabilities, authorization and resource ownership |
| Performance | Benchmarks, allocation tests and runtime profiling |
| Native type bundles | Versions, provenance and third-party licenses |
Repository rules are in AGENTS.md; validation commands are in CI. Rust builds independently of the optional Next.js UI.
Start the local test stack with docker compose -p arrpi-test -f deploy/compose.test.yaml up --build -d --wait. Refresh screenshots with uv run --locked scripts/screenshot.py --no-build. For the MCP demo, reset the disposable fixture stack with docker compose -p arrpi-test -f deploy/compose.test.yaml down --volumes, start it again, then run uv run --locked scripts/demo.py --model sonnet; it needs Claude Code, asciinema 3.2.1, agg 1.9.0 and FFmpeg. The default output is an MP4; add --upload to get a GitHub video attachment URL for the README.