MCP *arr Server

MCP server for the *arr media management suite - Sonarr, Radarr, Lidarr, and Prowlarr.

Supports both local stdio mode for Claude/Codex-style clients and remote HTTP mode for hosted MCP clients such as ChatGPT connectors.

Why Use This?

• Unified media management - Control all your *arr applications from one interface
• Natural language queries - Ask about your library in plain English
• Cross-service search - Find content across TV, movies, and music simultaneously
• Download monitoring - Check queue status and progress across all services
• Calendar integration - See upcoming releases for all media types
• Configuration review - Get AI-powered suggestions for optimizing your setup
• Flexible configuration - Enable only the services you use

Features

| Category | Capabilities | |----------|-------------| | Sonarr (TV) | List series, view episodes, search shows, trigger downloads, check queue, view calendar, review setup | | Radarr (Movies) | List movies, search films, trigger downloads, check queue, view releases, review setup | | Lidarr (Music) | List artists, view albums, search musicians, trigger downloads, check queue, view calendar, review setup | | Prowlarr (Indexers) | List indexers, search across all trackers, test health, view statistics | | Cross-Service | Status check, unified search across all configured services | | Configuration | Quality profiles, download clients, naming conventions, health checks, storage info | | TRaSH Guides | Reference quality profiles, custom formats, naming conventions, compare against recommendations |

Prerequisites

• Node.js 18+
• At least one *arr application running with API access:
  • Sonarr for TV series
  • Radarr for movies
  • Lidarr for music
  • Prowlarr for indexer management

Installation

Using npm (Recommended)

npx mcp-arr-server

Remote HTTP Mode

MCP_TRANSPORT=http PORT=3000 npx mcp-arr-server

By default the remote server listens on 127.0.0.1:3000 and serves MCP on /mcp.

Environment variables for remote mode:

• MCP_TRANSPORT=http to enable remote Streamable HTTP transport
• HOST to override the bind host (default 127.0.0.1)
• PORT to override the port (default 3000)
• MCP_PATH to override the MCP endpoint path (default /mcp)

Docker

Build locally:

docker build -t mcp-arr .

Run in local stdio mode:

docker run --rm -i \
  -e SONARR_URL=http://host.docker.internal:8989 \
  -e SONARR_API_KEY=your-sonarr-api-key \
  mcp-arr

Run in remote HTTP mode:

docker run --rm -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -e SONARR_URL=http://host.docker.internal:8989 \
  -e SONARR_API_KEY=your-sonarr-api-key \
  mcp-arr

Minimal docker-compose.yml:

services:
  mcp-arr:
    build: .
    ports:
      - "3000:3000"
    environment:
      MCP_TRANSPORT: http
      HOST: 0.0.0.0
      PORT: 3000
      SONARR_URL: http://host.docker.internal:8989
      SONARR_API_KEY: your-sonarr-api-key
      RADARR_URL: http://host.docker.internal:7878
      RADARR_API_KEY: your-radarr-api-key

From Source

git clone https://github.com/aplaceforallmystuff/mcp-arr.git
cd mcp-arr
npm install
npm run build

Configuration

Getting API Keys

Each *arr application has an API key in Settings > General > Security:

1. Open your *arr application's web interface
2. Go to Settings > General
3. Find the API Key under the Security section
4. Copy the API key for use in configuration

For Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "arr": {
      "command": "npx",
      "args": ["-y", "mcp-arr-server"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-sonarr-api-key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key",
        "LIDARR_URL": "http://localhost:8686",
        "LIDARR_API_KEY": "your-lidarr-api-key",
        "PROWLARR_URL": "http://localhost:9696",
        "PROWLARR_API_KEY": "your-prowlarr-api-key"
      }
    }
  }
}

For Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "arr": {
      "command": "npx",
      "args": ["-y", "mcp-arr-server"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-sonarr-api-key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key"
      }
    }
  }
}

Note: Only configure the services you have running. The server automatically detects which services are available based on the environment variables you provide.

TRaSH-only mode: if you don’t configure any *arr services, the server still starts and exposes the TRaSH Guides reference tools plus generic search and fetch.

ChatGPT / Remote MCP

To use mcp-arr with ChatGPT, run the server in remote HTTP mode on a reachable host and connect ChatGPT to the /mcp endpoint.

The server now exposes the generic search and fetch tools expected by ChatGPT-style remote MCP integrations:

• search discovers matching *arr media and TRaSH profiles
• fetch returns structured detail for a selected search result

The existing service-specific tools remain available for richer local or power-user workflows.

Usage Examples

Library Management

• "Show me all my TV series"
• "What movies do I have in Radarr?"
• "List all artists in my music library"

Searching & Adding Content

• "Search for sci-fi shows on Sonarr"
• "Find action movies from the 90s"
• "Add this show to my TV library"
• "Add that movie to Radarr"
• "Search for jazz albums and add this artist"
• "Add this movie with my '4k' tag"
• "What tags do I have in Sonarr?"

Download Queue

• "What's downloading right now?"
• "Check the Sonarr queue"
• "Show Radarr download progress"

Upcoming Releases

• "What TV episodes are coming this week?"
• "Show upcoming movie releases"
• "Any new albums coming out this month?"

Downloading Content

• "What episodes of this show am I missing?"
• "Download the missing episodes for that series"
• "Search for this specific movie"
• "Grab that album I'm missing"

Indexer Management

• "Are my indexers healthy?"
• "How are my indexers performing?"
• "Test all my Prowlarr indexers"

Configuration Review

• "Review my Sonarr setup and suggest improvements"
• "Show me my quality profiles in Radarr"
• "Are there any health issues with my Lidarr?"
• "What naming convention am I using for TV shows?"
• "Help me understand my quality profiles - why am I not getting 4K?"
• "Check my download client configuration"
• "How much free space do I have on my root folders?"

Cross-Service

• "Check status of all my *arr services"
• "Search for 'comedy' across all services"

Available Tools

General Tools

| Tool | Description | |------|-------------| | arr_status | Get connection status for all configured *arr services | | arr_search_all | Search across all configured services simultaneously | | search | Generic discovery tool for remote MCP clients such as ChatGPT | | fetch | Generic detail-fetch tool for items returned by search |

Sonarr Tools (TV)

| Tool | Description | |------|-------------| | sonarr_get_series | List all TV series in your library | | sonarr_search | Search for TV series by name (returns tvdbId for adding) | | sonarr_add_series | Add a TV series to Sonarr (supports tags) | | sonarr_get_root_folders | Get available root folders for adding series | | sonarr_get_quality_profiles | Get available quality profiles for adding series | | sonarr_get_queue | View current download queue with limit and offset pagination | | sonarr_get_calendar | See upcoming episodes | | sonarr_get_episodes | List episodes for a series (shows missing vs available) | | sonarr_search_missing | Trigger search for all missing episodes in a series | | sonarr_search_episode | Trigger search for specific episode(s) |

Radarr Tools (Movies)

| Tool | Description | |------|-------------| | radarr_get_movies | List all movies in your library | | radarr_search | Search for movies by name (returns tmdbId for adding) | | radarr_add_movie | Add a movie to Radarr (supports tags) | | radarr_get_root_folders | Get available root folders for adding movies | |