MCP *arr Server

Instructions

Implementation Reference

• src/arr-client.ts:906-914 (handler)

  Core handler function in ReadarrClient that executes the BookSearch command by POSTing to /command endpoint with bookIds.

  async searchBook(bookIds: number[]): Promise<{ id: number }> {
    return this['request']<{ id: number }>('/command', {
      method: 'POST',
      body: JSON.stringify({
        name: 'BookSearch',
        bookIds,
      }),
    });
  }

• src/index.ts:1507-1521 (handler)

  MCP server tool call handler that checks Readarr configuration, extracts bookIds from arguments, calls searchBook, and formats success response.

  case "readarr_search_book": {
    if (!clients.readarr) throw new Error("Readarr not configured");
    const bookIds = (args as { bookIds: number[] }).bookIds;
    const result = await clients.readarr.searchBook(bookIds);
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          success: true,
          message: `Search triggered for ${bookIds.length} book(s)`,
          commandId: result.id,
        }, null, 2),
      }],
    };
  }

• src/index.ts:488-502 (schema)

  Tool schema definition specifying input as array of bookIds (numbers), and registration in TOOLS array conditional on Readarr client configuration.

  {
    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"],
    },
  },

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

  Conditional registration of all Readarr tools including readarr_search_book into the MCP TOOLS array when Readarr client is configured.

  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: [],
        },
      }
    );