MCP *arr Server

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

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, music, and books 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
Readarr (Books)	List authors, view books, search writers, 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

Prerequisites

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

Installation

Using npm (Recommended)

npx mcp-arr-server

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",
        "READARR_URL": "http://localhost:8787",
        "READARR_API_KEY": "your-readarr-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.

Usage Examples

Library Management

• "Show me all my TV series"
• "What movies do I have in Radarr?"
• "List all artists in my music library"
• "How many books do I have by Stephen King?"

Searching for Content

• "Search for Breaking Bad on Sonarr"
• "Find the movie Inception"
• "Search for Taylor Swift albums"
• "Look up books by Brandon Sanderson"

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?"
• "Show me upcoming book releases"

Downloading Content

• "What episodes of Severance am I missing?"
• "Download the missing episodes for that show"
• "Search for this specific movie"
• "Grab that Japanese Breakfast album"
• "Download all missing books by Brandon Sanderson"

Indexer Management

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

Configuration Review (NEW)

• "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 'The Office' 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

Sonarr Tools (TV)

Tool	Description
sonarr_get_series	List all TV series in your library
sonarr_search	Search for TV series to add
sonarr_get_queue	View current download queue
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 to add
radarr_get_queue	View current download queue
radarr_get_calendar	See upcoming releases
radarr_search_movie	Trigger search to download a movie in your library

Lidarr Tools (Music)

Tool	Description
lidarr_get_artists	List all artists in your library
lidarr_search	Search for artists to add
lidarr_get_queue	View current download queue
lidarr_get_albums	List albums for an artist (shows missing vs available)
lidarr_search_album	Trigger search for a specific album
lidarr_search_missing	Trigger search for all missing albums for an artist
lidarr_get_calendar	See upcoming album releases

Readarr Tools (Books)

Tool	Description
readarr_get_authors	List all authors in your library
readarr_search	Search for authors to add
readarr_get_queue	View current download queue
readarr_get_books	List books for an author (shows missing vs available)
readarr_search_book	Trigger search for specific book(s)
readarr_search_missing	Trigger search for all missing books for an author
readarr_get_calendar	See upcoming book releases

Prowlarr Tools (Indexers)

Tool	Description
prowlarr_get_indexers	List all configured indexers
prowlarr_search	Search across all indexers
prowlarr_test_indexers	Test all indexers and return health status
prowlarr_get_stats	Get indexer statistics (queries, grabs, failures)

Configuration Review Tools

These tools are available for Sonarr, Radarr, Lidarr, and Readarr. Replace {service} with the service name (e.g., sonarr_get_quality_profiles).

Tool	Description
{service}_get_quality_profiles	Detailed quality profile information with allowed qualities and custom format scores
{service}_get_health	Health check warnings and issues detected by the application
{service}_get_root_folders	Storage paths, free space, and accessibility status
{service}_get_download_clients	Download client configurations and settings
{service}_get_naming	File and folder naming conventions
{service}_get_tags	Tag definitions for content organization
{service}_review_setup	Comprehensive configuration dump for AI-assisted setup analysis

The {service}_review_setup tool returns all configuration in a single call, enabling natural language conversations about optimizing your setup. Claude can analyze your quality profiles, suggest improvements, explain why certain content isn't being grabbed, and help configure complex settings like custom formats.

⚠️ Disclaimer: The configuration review tools provide read-only access to your *arr settings. Any changes to your configuration must be made directly in the *arr application interfaces. The AI's suggestions are recommendations only - always back up your configuration before making significant changes. The maintainers are not responsible for any configuration changes, data loss, or other issues that may arise from following AI-generated recommendations.

Development

# Watch mode for development
npm run watch

# Build TypeScript
npm run build

# Run locally
SONARR_URL="http://localhost:8989" SONARR_API_KEY="your-key" node dist/index.js

Troubleshooting

"No *arr services configured"

Ensure you have set at least one pair of URL and API_KEY environment variables:

SONARR_URL="http://localhost:8989"
SONARR_API_KEY="your-api-key"

"API error: 401 Unauthorized"

The API key is incorrect. Verify it in your *arr application under Settings > General > Security.

"fetch failed" or "ECONNREFUSED"

The *arr application is not running or the URL is incorrect. Verify:

• The application is running
• The URL and port are correct
• There's no firewall blocking the connection

"Sonarr/Radarr/etc not configured"

You tried to use a tool for a service that isn't configured. Add the corresponding URL and API_KEY environment variables.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE for details.

Links

• Servarr Wiki - Documentation for all *arr applications
• Sonarr API Docs
• Model Context Protocol
• GitHub Repository