MCP *arr Server

Instructions

Implementation Reference

• src/index.ts:1057-1079 (handler)

  MCP tool handler for 'sonarr_get_series': checks if Sonarr client is configured, fetches series list using client.getSeries(), formats summary statistics into JSON response
  case "sonarr_get_series": { if (!clients.sonarr) throw new Error("Sonarr not configured"); const series = await clients.sonarr.getSeries(); return { content: [{ type: "text", text: JSON.stringify({ count: series.length, series: series.map(s => ({ id: s.id, title: s.title, year: s.year, status: s.status, network: s.network, seasons: s.statistics?.seasonCount, episodes: s.statistics?.episodeFileCount + '/' + s.statistics?.totalEpisodeCount, sizeOnDisk: formatBytes(s.statistics?.sizeOnDisk || 0), monitored: s.monitored, })), }, null, 2), }], }; }
• src/arr-client.ts:600-602 (handler)

  Core implementation of SonarrClient.getSeries(): performs API GET request to '/api/v3/series' endpoint to retrieve all TV series
  async getSeries(): Promise<Series[]> { return this['request']<Series[]>('/series'); }
• src/index.ts:184-191 (registration)

  Registration of 'sonarr_get_series' tool: adds tool definition to TOOLS array (conditional on Sonarr client being configured), including name, description, and input schema
  name: "sonarr_get_series", description: "Get all TV series in Sonarr library", inputSchema: { type: "object" as const, properties: {}, required: [], }, },
• src/arr-client.ts:49-85 (schema)

  TypeScript interface defining the structure of Series objects returned by Sonarr API
  export interface Series { id: number; title: string; sortTitle: string; status: string; overview: string; network: string; airTime: string; images: Array<{ coverType: string; url: string }>; seasons: Array<{ seasonNumber: number; monitored: boolean }>; year: number; path: string; qualityProfileId: number; seasonFolder: boolean; monitored: boolean; runtime: number; tvdbId: number; tvRageId: number; tvMazeId: number; firstAired: string; seriesType: string; cleanTitle: string; imdbId: string; titleSlug: string; genres: string[]; tags: number[]; added: string; ratings: { votes: number; value: number }; statistics: { seasonCount: number; episodeFileCount: number; episodeCount: number; totalEpisodeCount: number; sizeOnDisk: number; percentOfEpisodes: number; }; }
• src/arr-client.ts:461-480 (helper)

  Base ArrClient.request() method: handles all API requests with authentication, error handling, and JSON parsing used by getSeries()
  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>; }