MCP *arr Server

Instructions

Implementation Reference

• src/index.ts:106-172 (registration)

  Dynamic registration of configuration review tools including sonarr_get_root_folders via addConfigTools function, called conditionally for Sonarr

  function addConfigTools(serviceName: string, displayName: string) {
    TOOLS.push(
      {
        name: `${serviceName}_get_quality_profiles`,
        description: `Get detailed quality profiles from ${displayName}. Shows allowed qualities, upgrade settings, and custom format scores.`,
        inputSchema: {
          type: "object" as const,
          properties: {},
          required: [],
        },
      },
      {
        name: `${serviceName}_get_health`,
        description: `Get health check warnings and issues from ${displayName}. Shows any problems detected by the application.`,
        inputSchema: {
          type: "object" as const,
          properties: {},
          required: [],
        },
      },
      {
        name: `${serviceName}_get_root_folders`,
        description: `Get root folders and storage info from ${displayName}. Shows paths, free space, and unmapped folders.`,
        inputSchema: {
          type: "object" as const,
          properties: {},
          required: [],
        },
      },
      {
        name: `${serviceName}_get_download_clients`,
        description: `Get download client configurations from ${displayName}. Shows configured clients and their settings.`,
        inputSchema: {
          type: "object" as const,
          properties: {},
          required: [],
        },
      },
      {
        name: `${serviceName}_get_naming`,
        description: `Get file naming configuration from ${displayName}. Shows naming patterns for files and folders.`,
        inputSchema: {
          type: "object" as const,
          properties: {},
          required: [],
        },
      },
      {
        name: `${serviceName}_get_tags`,
        description: `Get all tags defined in ${displayName}. Tags can be used to organize and filter content.`,
        inputSchema: {
          type: "object" as const,
          properties: {},
          required: [],
        },
      },
      {
        name: `${serviceName}_review_setup`,
        description: `Get comprehensive configuration review for ${displayName}. Returns all settings for analysis: quality profiles, download clients, naming, storage, indexers, health warnings, and more. Use this to analyze the setup and suggest improvements.`,
        inputSchema: {
          type: "object" as const,
          properties: {},
          required: [],
        },
      }
    );
  }

• src/index.ts:127-134 (schema)

  Tool schema definition for sonarr_get_root_folders (no input params required)

    name: `${serviceName}_get_root_folders`,
    description: `Get root folders and storage info from ${displayName}. Shows paths, free space, and unmapped folders.`,
    inputSchema: {
      type: "object" as const,
      properties: {},
      required: [],
    },
  },

• src/index.ts:856-880 (handler)

  MCP tool handler: extracts service from tool name, calls client.getRootFoldersDetailed(), formats response with folder count, paths, accessibility, free space (formatted and bytes), unmapped folder counts

  case "sonarr_get_root_folders":
  case "radarr_get_root_folders":
  case "lidarr_get_root_folders":
  case "readarr_get_root_folders": {
    const serviceName = name.split('_')[0] as keyof typeof clients;
    const client = clients[serviceName];
    if (!client) throw new Error(`${serviceName} not configured`);
    const folders = await client.getRootFoldersDetailed();
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          count: folders.length,
          folders: folders.map(f => ({
            id: f.id,
            path: f.path,
            accessible: f.accessible,
            freeSpace: formatBytes(f.freeSpace),
            freeSpaceBytes: f.freeSpace,
            unmappedFolders: f.unmappedFolders?.length || 0,
          })),
        }, null, 2),
      }],
    };
  }

• src/arr-client.ts:578-580 (helper)

  Core helper method in ArrClient (inherited by SonarrClient) that fetches detailed root folder data from /rootfolder API endpoint

  async getRootFoldersDetailed(): Promise<RootFolder[]> {
    return this.request<RootFolder[]>('/rootfolder');
  }

• src/arr-client.ts:461-480 (helper)

  Base request method used by all clients to make authenticated API calls to the *arr application

  protected async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
    const url = `${this.config.url}/api/${this.apiVersion}${endpoint}`;
    const headers: Record<string, string> = {
      'Content-Type': 'application/json',
      'X-Api-Key': this.config.apiKey,
      ...(options.headers as Record<string, string> || {}),
    };
  
    const response = await fetch(url, {
      ...options,
      headers,
    });
  
    if (!response.ok) {
      const text = await response.text();
      throw new Error(`${this.serviceName} API error: ${response.status} ${response.statusText} - ${text}`);
    }
  
    return response.json() as Promise<T>;
  }