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>; }