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