MCP *arr Server

Instructions

Implementation Reference

• src/arr-client.ts:611-616 (handler)

  Core handler implementation in SonarrClient.searchSeries: makes API call to Sonarr's /series/lookup endpoint with the search term.

  /**
   * Search for series
   */
  async searchSeries(term: string): Promise<SearchResult[]> {
    return this['request']<SearchResult[]>(`/series/lookup?term=${encodeURIComponent(term)}`);
  }

• src/index.ts:1081-1099 (handler)

  MCP server tool handler for 'sonarr_search': validates Sonarr client, calls searchSeries(term), limits to top 10 results, returns formatted JSON.

  case "sonarr_search": {
    if (!clients.sonarr) throw new Error("Sonarr not configured");
    const term = (args as { term: string }).term;
    const results = await clients.sonarr.searchSeries(term);
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          count: results.length,
          results: results.slice(0, 10).map(r => ({
            title: r.title,
            year: r.year,
            tvdbId: r.tvdbId,
            overview: r.overview?.substring(0, 200) + (r.overview && r.overview.length > 200 ? '...' : ''),
          })),
        }, null, 2),
      }],
    };
  }

• src/index.ts:193-205 (registration)

  Tool registration in TOOLS array (conditional on Sonarr client configured) with name, description, and input schema requiring 'term' string.

    name: "sonarr_search",
    description: "Search for TV series to add to Sonarr",
    inputSchema: {
      type: "object" as const,
      properties: {
        term: {
          type: "string",
          description: "Search term (show name)",
        },
      },
      required: ["term"],
    },
  },

• src/index.ts:195-205 (schema)

  Input schema definition for sonarr_search tool: object with required 'term' string property.

    inputSchema: {
      type: "object" as const,
      properties: {
        term: {
          type: "string",
          description: "Search term (show name)",
        },
      },
      required: ["term"],
    },
  },

• src/arr-client.ts:461-487 (helper)

  Base ArrClient.request method used by searchSeries to perform authenticated API requests to the *arr service.

  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>;
  }
  
  /**
   * Get system status
   */
  async getStatus(): Promise<SystemStatus> {
    return this.request<SystemStatus>('/system/status');
  }