MCP *arr Server

Instructions

Implementation Reference

• src/index.ts:1539-1560 (handler)

  MCP tool handler for 'readarr_get_calendar'. Computes date range from input 'days' (default 30), calls ReadarrClient.getCalendar(start, end), and returns count and list of upcoming books with id, title, authorId, releaseDate, monitored status.

  case "readarr_get_calendar": {
    if (!clients.readarr) throw new Error("Readarr not configured");
    const days = (args as { days?: number })?.days || 30;
    const start = new Date().toISOString().split('T')[0];
    const end = new Date(Date.now() + days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
    const calendar = await clients.readarr.getCalendar(start, end);
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          count: calendar.length,
          books: calendar.map(b => ({
            id: b.id,
            title: b.title,
            authorId: b.authorId,
            releaseDate: b.releaseDate,
            monitored: b.monitored,
          })),
        }, null, 2),
      }],
    };
  }

• src/index.ts:440-532 (registration)

  Conditional registration of Readarr tools in TOOLS array, including the schema definition for 'readarr_get_calendar' tool with optional 'days' parameter.

  if (clients.readarr) {
    TOOLS.push(
      {
        name: "readarr_get_authors",
        description: "Get all authors in Readarr library",
        inputSchema: {
          type: "object" as const,
          properties: {},
          required: [],
        },
      },
      {
        name: "readarr_search",
        description: "Search for authors to add to Readarr",
        inputSchema: {
          type: "object" as const,
          properties: {
            term: {
              type: "string",
              description: "Search term (author name)",
            },
          },
          required: ["term"],
        },
      },
      {
        name: "readarr_get_queue",
        description: "Get Readarr download queue",
        inputSchema: {
          type: "object" as const,
          properties: {},
          required: [],
        },
      },
      {
        name: "readarr_get_books",
        description: "Get books for an author in Readarr. Shows which books are available and which are missing.",
        inputSchema: {
          type: "object" as const,
          properties: {
            authorId: {
              type: "number",
              description: "Author ID to get books for",
            },
          },
          required: ["authorId"],
        },
      },
      {
        name: "readarr_search_book",
        description: "Trigger a search for a specific book to download",
        inputSchema: {
          type: "object" as const,
          properties: {
            bookIds: {
              type: "array",
              items: { type: "number" },
              description: "Book ID(s) to search for",
            },
          },
          required: ["bookIds"],
        },
      },
      {
        name: "readarr_search_missing",
        description: "Trigger a search for all missing books for an author",
        inputSchema: {
          type: "object" as const,
          properties: {
            authorId: {
              type: "number",
              description: "Author ID to search missing books for",
            },
          },
          required: ["authorId"],
        },
      },
      {
        name: "readarr_get_calendar",
        description: "Get upcoming book releases from Readarr",
        inputSchema: {
          type: "object" as const,
          properties: {
            days: {
              type: "number",
              description: "Number of days to look ahead (default: 30)",
            },
          },
          required: [],
        },
      }
    );
  }

• src/index.ts:518-530 (schema)

  Tool schema definition: name, description, and inputSchema with optional 'days' number parameter.

    name: "readarr_get_calendar",
    description: "Get upcoming book releases from Readarr",
    inputSchema: {
      type: "object" as const,
      properties: {
        days: {
          type: "number",
          description: "Number of days to look ahead (default: 30)",
        },
      },
      required: [],
    },
  }

• src/arr-client.ts:919-925 (helper)

  ReadarrClient.getCalendar method: constructs /calendar?start=...&end=... API endpoint and calls base request method to fetch upcoming Book[] releases.

  async getCalendar(start?: string, end?: string): Promise<Book[]> {
    const params = new URLSearchParams();
    if (start) params.append('start', start);
    if (end) params.append('end', end);
    const query = params.toString() ? `?${params.toString()}` : '';
    return this['request']<Book[]>(`/calendar${query}`);
  }

• src/arr-client.ts:499-505 (helper)

  Base ArrClient.getCalendar: generic implementation for /calendar endpoint used by all *arr clients (overridden in ReadarrClient for Book[] typing).

  async getCalendar(start?: string, end?: string): Promise<unknown[]> {
    const params = new URLSearchParams();
    if (start) params.append('start', start);
    if (end) params.append('end', end);
    const query = params.toString() ? `?${params.toString()}` : '';
    return this.request<unknown[]>(`/calendar${query}`);
  }