arr-mcp-server 0.4.0

MCP server for natural language management of home media server stacks

arr-mcp

MCP server for natural language management of a home media server stack — Plex, Sonarr, Radarr, SABnzbd, and more — via Podman or Docker.

Talk to your media server through Claude instead of SSH. Ask it to restart a stuck container, check disk usage, pull the latest images for a stack, or migrate a compose file to Podman quadlets. A read-only status dashboard is also included for household members who don't need Claude.

---

AI Disclosure

This project was co-authored with Claude (Anthropic). The architecture, code, and documentation were developed collaboratively. All code has been reviewed by the author and is maintained as a human-owned open source project.

---

Quick start

The easiest way to install on a Podman (rootless) server — run this as your service account:

bash <(curl -sSL https://raw.githubusercontent.com/ryanbrinn/arr-mcp/main/scripts/install/install.sh)

This installs arr-agent on the host, generates a quadlet for arr-mcp, and starts both services. It asks five questions (media directory, API key, etc.) and takes about a minute.

Requirements: rootless Podman, uv, active systemd user session (sudo loginctl enable-linger $(whoami)).

For Docker or manual setup, see the Getting Started guide.

---

What it does

Talk to your server through Claude

Connect arr-mcp to Claude as an MCP server and manage your stack conversationally:

"Restart the radarr container"
"How much disk space is left on /media-server?"
"Pull the latest images for my media stack and bring it back up"
"Convert my compose.yaml to quadlet files"

Status dashboard

An authenticated dashboard is served at http://your-server:8081/ — no Claude required. Shows container status, disk usage, and stack health with auto-refresh every 30 seconds. Household members sign in with a local account or Plex to view status and manage their media interests.

---

Features

Category	Tools
Containers	list, start, stop, restart, remove, logs, stats
Stacks	up, down, pull, restart, validate (via arr-agent)
Compose files	read, write, validate
Conversion	compose → quadlets, quadlets → compose
Filesystem	disk usage, directory list, file read, write, delete
Logs	tail and search any log file
Services	health checks, API reachability, diagnostics, version tracking
Media	watched-content cleanup, per-user interest states
Credentials	encrypted credential store for service API keys
Alerts	configurable threshold alerts with polling
Security	session auth, rate limiting, security headers, PBKDF2 encryption

All filesystem operations are ownership-scoped — arr-mcp cannot touch files owned by root or other users. See Security.

---

Architecture

Claude / Browser
      │
      ▼
 arr-mcp (container)          ← MCP tools + dashboard
      │  Podman socket
      ▼
 Container runtime             ← your media stack

 arr-agent (host process)     ← podman-compose, systemctl, quadlets
      │  Unix socket (bind-mounted into arr-mcp)
      ▼
 arr-mcp container

arr-agent is a small host-side process that gives arr-mcp access to podman-compose, systemctl --user, and quadlet files — things that aren't available from inside a container. The install script sets it up automatically.

---

Connecting to Claude

Claude.ai

Go to Settings → Integrations and add a remote MCP server:

URL:    http://your-server-ip:8081/mcp
Header: Authorization: Bearer your-api-key

Claude Desktop

Claude Desktop requires a local bridge. Install mcpproxy on your local machine, then add to claude_desktop_config.json:

{
  "mcpServers": {
    "arr-mcp": {
      "command": "/usr/local/bin/mcpproxy",
      "args": [
        "--transport", "streamablehttp",
        "-H", "Authorization", "Bearer your-api-key",
        "http://your-server-ip:8081/mcp"
      ]
    }
  }
}

---

Configuration

Variable	Default	Description
ARR_MCP_API_KEY	``	Bearer token — required (server refuses to start if empty or changeme)
ARR_MCP_PORT	8081	HTTP listen port
ARR_MCP_SERVICES_DIR	/media-server	Root directory where arr services live (configs, logs, data) — read-only
ARR_MCP_MEDIA_DIR	/media-server/library	Root directory of your media library
ARR_MCP_COMPOSE_DIR	``	Root directory for Docker Compose projects — required for docker-compose runtime
ARR_MCP_CONTAINER_RUNTIME	docker-compose	docker-compose / docker / podman / auto
ARR_MCP_SOCKET_PATH	``	Explicit runtime socket path (required in containers)
ARR_MCP_HELPER_SOCKET	/run/arr-agent/arr-agent.sock	arr-agent socket path
ARR_MCP_SESSION_SECRET	``	Secret for signing session cookies — required
ARR_MCP_ADMIN_USERS	``	Comma-separated usernames granted admin on first login
ARR_MCP_LOG_LEVEL	info	debug / info / warning / error

Full reference: docs/configuration.

---

Supported runtimes

Configuration	Supported
Docker Engine	✅
Docker with Docker Compose	✅
Podman (rootless) with Quadlets	✅
Podman (rooted)	❌

---

Documentation

• Getting Started
• Tools Reference
• Configuration
• Security
• Architecture
• Roadmap

---

Contributing

git clone https://github.com/ryanbrinn/arr-mcp
cd arr-mcp
uv sync --extra dev
uv run pytest

See CLAUDE.md for development guidelines.

---

License

MIT