Arr Assistant

This MCP server enables you to search for movies and TV shows and automatically add them to Radarr and Sonarr, making it easier to manage your media library from a single place.

How to use

To use this MCP server, connect a compatible MCP client to the local or remote endpoint. You can search for movies, add movies by their database ID, search and optionally auto-add TV shows, and verify the connection status with the server. Use the provided tools to perform the actions you need, such as searching for titles, adding items to Radarr or Sonarr, and checking that both services are reachable.

How to install

Prerequisites you need before installing this MCP server are Python 3.12 or newer and the uv runner for local development.

git clone <repo>
cd arr-assistant-mcp
uv sync

Additional sections

Configuration notes and practical usage details are provided to help you customize the server to your Radarr and Sonarr instances. You should configure API keys, root folders, and any required IDs according to your setup. The server can automatically detect root folders if you omit them, and the TVDB API key is not required for the current implementation.

From source, you can run the MCP server directly from your development environment by adding a MCP configuration entry that uses uv to run the project. The configuration includes paths to your local clone and environment variables for Radarr and Sonarr.

{
  "mcpServers": {
    "arr-assistant": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/arr-assistant-mcp",
        "src/arr_assistant_mcp/main.py"
      ],
      "env": {
        "RADARR_URL": "http://your-ip:7878",
        "RADARR_API_KEY": "your-radarr-api-key",
        "SONARR_URL": "http://your-ip:8989",
        "SONARR_API_KEY": "your-sonarr-api-key",
        "QUALITY_PROFILE_ID": "1",
        "RADARR_ROOT_FOLDER": "/storage/movies",
        "SONARR_ROOT_FOLDER": "/storage/shows"
      }
    }
  }
}

Build an MCP bundle

When you’re ready to package a release, use the MCP bundle tooling to create a distributable file that others can install.

npm install -g @anthropic-ai/mcpb
mcpb validate .
mcpb pack . arr-assistant-mcp.mcpb

Notes on configuration and usage

• Radarr/Sonarr API keys are found under Settings > General > API Key in each application.

• The quality profile uses the numeric profile ID from Radarr or Sonarr.

• If not provided, the server auto-detects the first available root folder from each service.

• TVDB API key is not required for the current implementation.

Available tools

test_config

Test configuration and connectivity for both Radarr and Sonarr

search_movies

Search for movies by title in Radarr-compatible index

add_movie_by_id

Add a movie to Radarr by its TMDB ID, with an optional root folder

search_and_add_show

Search for TV shows by description and optionally auto-add the only match to Sonarr

add_show_by_tvdb_id

Add a show to Sonarr by its TVDB ID and title, with an optional root folder

get_server_status

Check the connection and status of Radarr and Sonarr