MCP *arr Server

Instructions

Implementation Reference

• src/arr-client.ts:878-881 (handler)

  Core implementation of fetching books for a given author ID from the Readarr API endpoint /api/v1/book?authorId={authorId}. Uses the base request method.
  async getBooks(authorId?: number): Promise<Book[]> { const url = authorId ? `/book?authorId=${authorId}` : '/book'; return this['request']<Book[]>(url); }
• src/index.ts:1483-1505 (handler)

  MCP server tool handler for 'readarr_get_books'. Validates configuration, calls ReadarrClient.getBooks(authorId), formats the books data with counts, summaries, and disk sizes, returns as JSON text content.
  case "readarr_get_books": { if (!clients.readarr) throw new Error("Readarr not configured"); const authorId = (args as { authorId: number }).authorId; const books = await clients.readarr.getBooks(authorId); return { content: [{ type: "text", text: JSON.stringify({ count: books.length, books: books.map(b => ({ id: b.id, title: b.title, releaseDate: b.releaseDate, pageCount: b.pageCount, monitored: b.monitored, hasFile: b.statistics ? b.statistics.bookFileCount > 0 : false, sizeOnDisk: formatBytes(b.statistics?.sizeOnDisk || 0), grabbed: b.grabbed, })), }, null, 2), }], }; }
• src/index.ts:475-487 (registration)

  Tool registration in the MCP server's TOOLS array, including name, description, and input schema requiring authorId.
  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"], }, },
• src/arr-client.ts:112-140 (schema)

  TypeScript interface defining the Book structure returned by the Readarr API and used in getBooks.
  export interface Book { id: number; title: string; authorId: number; foreignBookId: string; titleSlug: string; overview: string; releaseDate: string; pageCount: number; monitored: boolean; grabbed: boolean; ratings: { votes: number; value: number }; editions: Array<{ id: number; bookId: number; foreignEditionId: string; title: string; pageCount: number; isEbook: boolean; monitored: boolean; }>; statistics?: { bookFileCount: number; bookCount: number; totalBookCount: number; sizeOnDisk: number; percentOfBooks: number; }; }