MCP *arr Server

Instructions

Implementation Reference

• src/index.ts:518-529 (registration)

  Registers the readarr_get_calendar tool in the TOOLS array, including its name, description, and input schema (days parameter). Only added if Readarr client is configured.
  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:520-529 (schema)

  Defines the input schema for the tool: optional 'days' number parameter.
  inputSchema: { type: "object" as const, properties: { days: { type: "number", description: "Number of days to look ahead (default: 30)", }, }, required: [], },
• src/index.ts:1539-1560 (handler)

  Main handler for the tool call: validates Readarr config, computes date range from 'days' param (default 30), calls ReadarrClient.getCalendar, formats and returns upcoming books with count and basic details.
  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/arr-client.ts:919-925 (helper)

  ReadarrClient.getCalendar method: constructs /calendar API query with start/end dates and fetches data via generic request method.
  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:461-481 (helper)

  ArrClient.request: core HTTP request method used by getCalendar, handles API calls to Readarr with auth and error handling.
  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>; }