arr-assistant

Simple MCP server for adding media to 'arr software (radarr, sonarr)

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio omniwaifu-arr-assistant-mcp uv run --project /path/to/arr-assistant-mcp src/arr_assistant_mcp/main.py \
  --env RADARR_URL="http://your-ip:7878" \
  --env SONARR_URL="http://your-ip:8989" \
  --env RADARR_API_KEY="your-radarr-api-key" \
  --env SONARR_API_KEY="your-sonarr-api-key" \
  --env QUALITY_PROFILE_ID="1" \
  --env RADARR_ROOT_FOLDER="/storage/movies" \
  --env SONARR_ROOT_FOLDER="/storage/shows"

How to use

The arr-assistant MCP server provides tools to search for movies and TV shows and add them to Radarr and Sonarr. Use the included helpers to perform searches, verify results, and push selections to your media managers. Typical workflows include searching for a movie by title, adding a movie by its TMDB ID to Radarr, or searching for a TV show by description and optionally auto-adding the only match to Sonarr. Root folders can be auto-detected from your Radarr and Sonarr configurations or overridden per request. The server exposes functions such as test_config(), search_movies(title), add_movie_by_id(tmdb_id, root_folder=None), search_and_add_show(description, auto_add=False), add_show_by_tvdb_id(tvdb_id, title, root_folder=None), and get_server_status() to help you manage media ingestion and verify connectivity.

How to install

Prerequisites:\n- Python 3.12+\n- uv (for local development)\n\nInstallation steps:\n1) Clone the repository:\n git clone <repo-url>\n cd arr-assistant-mcp\n\n2) Install Python dependencies (if any are specified in a requirements file):\n python -m pip install -r requirements.txt # if such a file exists\n\n3) Install and run with uv for local development:\n uv sync # set up the local project workspace and dependencies\n\n4) Run the server from source (example):\n uv run --project /path/to/arr-assistant-mcp src/arr_assistant_mcp/main.py\n\n5) Package for Claude Desktop (optional):\n npm install -g @anthropic-ai/mcpb\n mcpb validate .\n mcpb pack . arr-assistant-mcp.mcpb\n\nPrerequisites notes:\n- Ensure RADARR_URL, RADARR_API_KEY, SONARR_URL, and SONARR_API_KEY are configured as needed.\n- If you omit root folders, the server will auto-detect them from Radarr/Sonarr.\n- The TVDB API key is not required for the current implementation.

Additional notes

Tips and notes:\n- Trailing slashes in RADARR_URL and SONARR_URL are normalized automatically.\n- Quality profile ID should be the numeric profile ID from Radarr/Sonarr you want to apply to added items.\n- TVDB API key is not required for the current implementation.\n- If you need to override root folders per request, provide RADARR_ROOT_FOLDER and SONARR_ROOT_FOLDER in the per-request environment or call context.\n- Ensure your Radarr and Sonarr instances are accessible from the machine running the MCP server (network/firewall rules permitting).