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

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

Full reference: docs/configuration.

Supported runtimes

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