MCP *arr Server

Instructions

Implementation Reference

• src/index.ts:230-246 (registration)

  Registration of the 'sonarr_get_episodes' tool in the TOOLS array, including name, description, and input schema. Added conditionally if Sonarr client is configured.

    name: "sonarr_get_episodes",
    description: "Get episodes for a TV series. Shows which episodes are available and which are missing.",
    inputSchema: {
      type: "object" as const,
      properties: {
        seriesId: {
          type: "number",
          description: "Series ID to get episodes for",
        },
        seasonNumber: {
          type: "number",
          description: "Optional: filter to a specific season",
        },
      },
      required: ["seriesId"],
    },
  },

• src/index.ts:1132-1153 (handler)

  MCP tool handler for 'sonarr_get_episodes': validates Sonarr config, extracts args, calls SonarrClient.getEpisodes(), formats response as JSON.

  case "sonarr_get_episodes": {
    if (!clients.sonarr) throw new Error("Sonarr not configured");
    const { seriesId, seasonNumber } = args as { seriesId: number; seasonNumber?: number };
    const episodes = await clients.sonarr.getEpisodes(seriesId, seasonNumber);
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          count: episodes.length,
          episodes: episodes.map(e => ({
            id: e.id,
            seasonNumber: e.seasonNumber,
            episodeNumber: e.episodeNumber,
            title: e.title,
            airDate: e.airDate,
            hasFile: e.hasFile,
            monitored: e.monitored,
          })),
        }, null, 2),
      }],
    };
  }

• src/arr-client.ts:651-657 (handler)

  Core implementation in SonarrClient: constructs API endpoint /api/v3/episode?seriesId=... [&seasonNumber=...] and fetches episodes via base request method.

  async getEpisodes(seriesId: number, seasonNumber?: number): Promise<Episode[]> {
    let url = `/episode?seriesId=${seriesId}`;
    if (seasonNumber !== undefined) {
      url += `&seasonNumber=${seasonNumber}`;
    }
    return this['request']<Episode[]>(url);
  }