arr-mcp 0.12.0

Arr Suite MCP Server for Agentic AI!

Arr Stack - A2A | AG-UI | MCP

Version: 0.12.0

Overview

Arr Stack MCP Server + A2A Server

It includes a Model Context Protocol (MCP) server and an out of the box Agent2Agent (A2A) agent.

This server is a consolidated MCP server for the entire Arr stack, providing a single entry point for AI agents to interact with your media management services. Each service's tools can be enabled or disabled independently via environment variables.

This repository is actively maintained - Contributions are welcome!

Supports:

• Sonarr: TV series management (SONARRTOOL)
• Radarr: Movie collection management (RADARRTOOL)
• Lidarr: Music collection management (LIDARRTOOL)
• Prowlarr: Indexer management (PROWLARRTOOL)
• Bazarr: Subtitle management (BAZARRTOOL)
• Seerr: Media request management (SEERRTOOL)
• Chaptarr: Book/Audiobook management (CHAPTARRTOOL)
• Centralized authentication

MCP

MCP Tools

All tools are registered directly in a single consolidated server. Enable or disable each service via environment variables.

Service	Description	Env Variable	Default
sonarr	Tools for managing TV shows (add, search, monitor)	SONARRTOOL	True
radarr	Tools for managing movies (add, search, monitor)	RADARRTOOL	True
lidarr	Tools for managing music (add, search, monitor)	LIDARRTOOL	True
prowlarr	Tools for managing indexers	PROWLARRTOOL	True
bazarr	Tools for managing subtitles	BAZARRTOOL	True
seerr	Tools for managing media requests	SEERRTOOL	True
chaptarr	Tools for managing books and audiobooks	CHAPTARRTOOL	True

Using as an MCP Server

The MCP Server can be run in two modes: stdio (for local testing) or http (for networked access). To start the server, use the following commands:

Run in stdio mode (default):

arr-mcp --transport "stdio"

Run in HTTP mode:

arr-mcp --transport "http"  --host "0.0.0.0"  --port "8000"

AI Prompt:

Find the movie Inception

AI Response:

Found movie "Inception" (2010). It is currently monitored and available on disk.

A2A Agent

This package also includes an A2A agent server that can be used to interact with the Arr MCP server.

Architecture:

---
config:
  layout: dagre
---
flowchart TB
 subgraph subGraph0["Agent Capabilities"]
        C["Agent"]
        B["A2A Server - Uvicorn/FastAPI"]
        D["MCP Tools"]
        F["Agent Skills"]
  end
    C --> D & F
    A["User Query"] --> B
    B --> C
    D --> E["Radarr/Sonarr/etc API"]

     C:::agent
     B:::server
     A:::server
    classDef server fill:#f9f,stroke:#333
    classDef agent fill:#bbf,stroke:#333,stroke-width:2px
    style B stroke:#000000,fill:#FFD600
    style D stroke:#000000,fill:#BBDEFB
    style F fill:#BBDEFB
    style A fill:#C8E6C9
    style subGraph0 fill:#FFF9C4

Component Interaction Diagram

sequenceDiagram
    participant User
    participant Server as A2A Server
    participant Agent as Agent
    participant Skill as Agent Skills
    participant MCP as MCP Tools
    participant API as Arr Application

    User->>Server: Send Query
    Server->>Agent: Invoke Agent
    Agent->>Skill: Analyze Skills Available
    Skill->>Agent: Provide Guidance on Next Steps
    Agent->>MCP: Invoke Tool
    MCP->>API: Call API (e.g. Radarr)
    API-->>MCP: API Response
    MCP-->>Agent: Tool Response Returned
    Agent-->>Agent: Return Results Summarized
    Agent-->>Server: Final Response
    Server-->>User: Output

Graph Architecture

This agent uses pydantic-graph orchestration for intelligent routing and optimal context management.

---
title: Arr Suite Graph Agent
---
stateDiagram-v2
  [*] --> RouterNode: User Query
  RouterNode --> DomainNode: Classified Domain
  RouterNode --> [*]: Low confidence / Error
  DomainNode --> [*]: Domain Result

• RouterNode: A fast, lightweight LLM (e.g., nvidia/nemotron-3-super) that classifies the user's query into one of the specialized domains.
• DomainNode: The executor node. For the selected domain, it dynamically sets environment variables to temporarily enable ONLY the tools relevant to that domain, creating a highly focused sub-agent (e.g., gpt-4o) to complete the request. This preserves LLM context and prevents tool hallucination.

Usage

MCP CLI

Short Flag	Long Flag	Description
-h	--help	Display help information
-t	--transport	Transport method: 'stdio', 'streamable-http', or 'sse' [legacy] (default: stdio)
-s	--host	Host address for HTTP transport (default: 0.0.0.0)
-p	--port	Port number for HTTP transport (default: 8000)
	--auth-type	Authentication type: 'none', 'static', 'jwt', 'oauth-proxy', 'oidc-proxy', 'remote-oauth' (default: none)
	--enable-delegation	Enable OIDC token delegation
	--eunomia-type	Eunomia authorization type: 'none', 'embedded', 'remote' (default: none)

A2A CLI

Endpoints

• Web UI: http://localhost:8000/ (if enabled)
• A2A: http://localhost:8000/a2a (Discovery: /a2a/.well-known/agent.json)
• AG-UI: http://localhost:8000/ag-ui (POST)

Short Flag	Long Flag	Description
-h	--help	Display help information
	--host	Host to bind the server to (default: 0.0.0.0)
	--port	Port to bind the server to (default: 9000)
	--reload	Enable auto-reload
	--provider	LLM Provider: 'openai', 'anthropic', 'google', 'huggingface'
	--model-id	LLM Model ID (default: nvidia/nemotron-3-super)
	--base-url	LLM Base URL (for OpenAI compatible providers)
	--api-key	LLM API Key
	--mcp-url	MCP Server URL (default: http://localhost:8000/mcp)
	--mcp-config	Path to mcp_config.json
	--web	Enable Pydantic AI Web UI

Agentic AI

arr-mcp is designed to be used by Agentic AI systems. It provides a set of tools that allow agents to manage your media library.

Agent-to-Agent (A2A)

This package also includes an A2A agent server that can be used to interact with the Arr MCP server.

Examples

Run A2A Server

arr-agent --provider openai --model-id gpt-4 --api-key sk-... --mcp-url http://localhost:8000/mcp

Run with Docker

docker run -e CMD=arr-agent -p 8000:8000 arr-mcp

Docker

Build

docker build -t arr-mcp .

Run MCP Server

docker run -p 8000:8000 arr-mcp

Run A2A Server

docker run -e CMD=arr-agent -p 8001:8001 arr-mcp

Deploy MCP Server as a Service

The Arr MCP server can be deployed using Docker, with configurable authentication, middleware, and Eunomia authorization.

Using Docker Run

docker pull knucklessg1/arr-mcp:latest

# Run with all services enabled (default)
docker run -d \
  --name arr-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=streamable-http \
  -e AUTH_TYPE=none \
  -e SONARR_BASE_URL=http://sonarr:8989 \
  -e SONARR_API_KEY=your-sonarr-key \
  -e RADARR_BASE_URL=http://radarr:7878 \
  -e RADARR_API_KEY=your-radarr-key \
  knucklessg1/arr-mcp:latest

# Run with only Sonarr and Radarr enabled
docker run -d \
  --name arr-mcp \
  -p 8004:8004 \
  -e TRANSPORT=streamable-http \
  -e SONARR_BASE_URL=http://sonarr:8989 \
  -e SONARR_API_KEY=your-sonarr-key \
  -e RADARR_BASE_URL=http://radarr:7878 \
  -e RADARR_API_KEY=your-radarr-key \
  -e SONARRTOOL=True \
  -e RADARRTOOL=True \
  -e LIDARRTOOL=False \
  -e PROWLARRTOOL=False \
  -e BAZARRTOOL=False \
  -e SEERRTOOL=False \
  -e CHAPTARRTOOL=False \
  knucklessg1/arr-mcp:latest

Using Docker Compose

Create a docker-compose.yml file:

services:
  arr-mcp:
    image: knucklessg1/arr-mcp:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8004
      - TRANSPORT=streamable-http
      - AUTH_TYPE=none
      # Service API Connections
      - SONARR_BASE_URL=http://sonarr:8989
      - SONARR_API_KEY=${SONARR_API_KEY}
      - RADARR_BASE_URL=http://radarr:7878
      - RADARR_API_KEY=${RADARR_API_KEY}
      - LIDARR_BASE_URL=http://lidarr:8686
      - LIDARR_API_KEY=${LIDARR_API_KEY}
      - PROWLARR_BASE_URL=http://prowlarr:9696
      - PROWLARR_API_KEY=${PROWLARR_API_KEY}
      - BAZARR_BASE_URL=http://bazarr:6767
      - BAZARR_API_KEY=${BAZARR_API_KEY}
      # Tool Tag Flags (all default to True)
      - SONARRTOOL=True
      - RADARRTOOL=True
      - LIDARRTOOL=True
      - PROWLARRTOOL=True
      - BAZARRTOOL=True
      - SEERRTOOL=True
      - CHAPTARRTOOL=True
    ports:
      - 8004:8004

Configure mcp_config.json for AI Integration

{
  "mcpServers": {
    "arr-mcp": {
      "command": "arr-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "SONARR_BASE_URL": "http://sonarr:8989",
        "SONARR_API_KEY": "your-sonarr-key",
        "RADARR_BASE_URL": "http://radarr:7878",
        "RADARR_API_KEY": "your-radarr-key",
        "SONARRTOOL": "True",
        "RADARRTOOL": "True",
        "LIDARRTOOL": "False",
        "PROWLARRTOOL": "False",
        "BAZARRTOOL": "False",
        "SEERRTOOL": "False",
        "CHAPTARRTOOL": "False"
      }
    }
  }
}

Install Python Package

python -m pip install arr-mcp

uv pip install arr-mcp

Repository Owners

MCP Configuration Examples

1. Standard IO (stdio) Deployment

{
  "mcpServers": {
    "arr-mcp": {
      "command": "uv",
      "args": [
        "run",
        "arr-mcp"
      ],
      "env": {
        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
        "BAZARR_CATALOGTOOL": "True",
        "BAZARR_HISTORYTOOL": "True",
        "BAZARR_SYSTEMTOOL": "True",
        "CHAPTARR_CONFIGTOOL": "True",
        "CHAPTARR_DOWNLOADSTOOL": "True",
        "CHAPTARR_HISTORYTOOL": "True",
        "CHAPTARR_INDEXERTOOL": "True",
        "CHAPTARR_OPERATIONSTOOL": "True",
        "CHAPTARR_PROFILESTOOL": "True",
        "CHAPTARR_QUEUETOOL": "True",
        "CHAPTARR_SEARCHTOOL": "True",
        "CHAPTARR_SYSTEMTOOL": "True",
        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
        "LIDARR_CATALOGTOOL": "True",
        "LIDARR_CONFIGTOOL": "True",
        "LIDARR_DOWNLOADSTOOL": "True",
        "LIDARR_HISTORYTOOL": "True",
        "LIDARR_INDEXERTOOL": "True",
        "LIDARR_OPERATIONSTOOL": "True",
        "LIDARR_PROFILESTOOL": "True",
        "LIDARR_QUEUETOOL": "True",
        "LIDARR_SEARCHTOOL": "True",
        "LIDARR_SYSTEMTOOL": "True",
        "PROWLARR_CONFIGTOOL": "True",
        "PROWLARR_DOWNLOADSTOOL": "True",
        "PROWLARR_HISTORYTOOL": "True",
        "PROWLARR_INDEXERTOOL": "True",
        "PROWLARR_OPERATIONSTOOL": "True",
        "PROWLARR_PROFILESTOOL": "True",
        "PROWLARR_SEARCHTOOL": "True",
        "PROWLARR_SYSTEMTOOL": "True",
        "RADARR_CATALOGTOOL": "True",
        "RADARR_CONFIGTOOL": "True",
        "RADARR_DOWNLOADSTOOL": "True",
        "RADARR_HISTORYTOOL": "True",
        "RADARR_INDEXERTOOL": "True",
        "RADARR_OPERATIONSTOOL": "True",
        "RADARR_PROFILESTOOL": "True",
        "RADARR_QUEUETOOL": "True",
        "RADARR_SYSTEMTOOL": "True",
        "SEERR_CATALOGTOOL": "True",
        "SEERR_SEARCHTOOL": "True",
        "SEERR_SYSTEMTOOL": "True",
        "SONARR_CATALOGTOOL": "True",
        "SONARR_CONFIGTOOL": "True",
        "SONARR_DOWNLOADSTOOL": "True",
        "SONARR_HISTORYTOOL": "True",
        "SONARR_INDEXERTOOL": "True",
        "SONARR_OPERATIONSTOOL": "True",
        "SONARR_PROFILESTOOL": "True",
        "SONARR_QUEUETOOL": "True",
        "SONARR_SYSTEMTOOL": "True"
      }
    }
  }
}

2. Streamable HTTP (SSE) Deployment

{
  "mcpServers": {
    "arr-mcp": {
      "command": "uv",
      "args": [
        "run",
        "arr-mcp",
        "--transport",
        "http",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
        "BAZARR_CATALOGTOOL": "True",
        "BAZARR_HISTORYTOOL": "True",
        "BAZARR_SYSTEMTOOL": "True",
        "CHAPTARR_CONFIGTOOL": "True",
        "CHAPTARR_DOWNLOADSTOOL": "True",
        "CHAPTARR_HISTORYTOOL": "True",
        "CHAPTARR_INDEXERTOOL": "True",
        "CHAPTARR_OPERATIONSTOOL": "True",
        "CHAPTARR_PROFILESTOOL": "True",
        "CHAPTARR_QUEUETOOL": "True",
        "CHAPTARR_SEARCHTOOL": "True",
        "CHAPTARR_SYSTEMTOOL": "True",
        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
        "LIDARR_CATALOGTOOL": "True",
        "LIDARR_CONFIGTOOL": "True",
        "LIDARR_DOWNLOADSTOOL": "True",
        "LIDARR_HISTORYTOOL": "True",
        "LIDARR_INDEXERTOOL": "True",
        "LIDARR_OPERATIONSTOOL": "True",
        "LIDARR_PROFILESTOOL": "True",
        "LIDARR_QUEUETOOL": "True",
        "LIDARR_SEARCHTOOL": "True",
        "LIDARR_SYSTEMTOOL": "True",
        "PROWLARR_CONFIGTOOL": "True",
        "PROWLARR_DOWNLOADSTOOL": "True",
        "PROWLARR_HISTORYTOOL": "True",
        "PROWLARR_INDEXERTOOL": "True",
        "PROWLARR_OPERATIONSTOOL": "True",
        "PROWLARR_PROFILESTOOL": "True",
        "PROWLARR_SEARCHTOOL": "True",
        "PROWLARR_SYSTEMTOOL": "True",
        "RADARR_CATALOGTOOL": "True",
        "RADARR_CONFIGTOOL": "True",
        "RADARR_DOWNLOADSTOOL": "True",
        "RADARR_HISTORYTOOL": "True",
        "RADARR_INDEXERTOOL": "True",
        "RADARR_OPERATIONSTOOL": "True",
        "RADARR_PROFILESTOOL": "True",
        "RADARR_QUEUETOOL": "True",
        "RADARR_SYSTEMTOOL": "True",
        "SEERR_CATALOGTOOL": "True",
        "SEERR_SEARCHTOOL": "True",
        "SEERR_SYSTEMTOOL": "True",
        "SONARR_CATALOGTOOL": "True",
        "SONARR_CONFIGTOOL": "True",
        "SONARR_DOWNLOADSTOOL": "True",
        "SONARR_HISTORYTOOL": "True",
        "SONARR_INDEXERTOOL": "True",
        "SONARR_OPERATIONSTOOL": "True",
        "SONARR_PROFILESTOOL": "True",
        "SONARR_QUEUETOOL": "True",
        "SONARR_SYSTEMTOOL": "True"
      }
    }
  }
}