OpenSubtitles MCP Server

Instructions

Implementation Reference

• src/tools/download-subtitle.ts:16-116 (handler)

  The primary handler function that implements the download_subtitle tool logic. It validates inputs using Zod, handles authentication (API key or username/password login), requests download link from OpenSubtitles API, fetches subtitle content, and returns formatted JSON response with error handling.
  export async function downloadSubtitle(args: unknown) { try { // Validate input arguments const validatedArgs = DownloadArgsSchema.parse(args); // Extract authentication parameters from args const { user_api_key, username, password, file_id, file_name, in_fps, out_fps, timeshift, force_download } = validatedArgs; // Create API client const client = new OpenSubtitlesKongClient(); // Handle authentication let authValue: string | undefined = user_api_key; let isToken = false; // If username/password provided, login to get token if (username && password && !user_api_key) { try { const loginResponse = await client.login({ username, password }); authValue = loginResponse.token; isToken = true; console.error(`DEBUG: Successfully logged in user ${username}, got token`); } catch (loginError) { console.error("DEBUG: Login failed:", loginError); // Continue with default API key (authValue will be undefined) } } // Request download link const downloadParams: any = { file_id: file_id, }; // Add optional parameters if (file_name) downloadParams.file_name = file_name; if (in_fps !== undefined) downloadParams.in_fps = in_fps; if (out_fps !== undefined) downloadParams.out_fps = out_fps; if (timeshift !== undefined) downloadParams.timeshift = timeshift; // Always set force_download to ensure direct file download with proper headers downloadParams.force_download = force_download; const downloadInfo = await client.downloadSubtitle( downloadParams, authValue, isToken ); // Download the actual subtitle content const subtitleContent = await client.downloadSubtitleContent(downloadInfo.link); // Format response const response = { file_id: file_id, file_name: downloadInfo.file_name, content: subtitleContent, force_download: force_download, download_info: { requests_used: downloadInfo.requests, requests_remaining: downloadInfo.remaining, reset_time: downloadInfo.reset_time, reset_time_utc: downloadInfo.reset_time_utc, message: downloadInfo.message, }, }; return { content: [ { type: "text", text: JSON.stringify(response, null, 2), }, ], }; } catch (error) { console.error("Download subtitle error:", error); let errorMessage = "Failed to download subtitle"; if (error instanceof z.ZodError) { errorMessage = `Invalid parameters: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`; } else if (error instanceof Error) { errorMessage = error.message; } // Provide helpful error messages based on common issues if (errorMessage.includes("429")) { errorMessage += "\n\nTo download subtitles, you need an OpenSubtitles API key. Get one free at: https://www.opensubtitles.com/api"; } else if (errorMessage.includes("401")) { errorMessage += "\n\nYour API key may be invalid. Please check it at: https://www.opensubtitles.com/api"; } return { content: [ { type: "text", text: `Error: ${errorMessage}`, }, ], }; } }
• src/tools/download-subtitle.ts:4-14 (schema)

  Zod schema used for input validation within the download_subtitle handler.
  const DownloadArgsSchema = z.object({ file_id: z.number(), file_name: z.string().optional(), in_fps: z.number().optional(), out_fps: z.number().optional(), timeshift: z.number().optional(), force_download: z.boolean().optional().default(true), // Default to true for direct file download user_api_key: z.string().optional(), username: z.string().optional(), password: z.string().optional(), });
• src/server.ts:110-156 (registration)

  MCP tool registration defining the download_subtitle tool, including its name, description, and JSON input schema for the server.
  { name: "download_subtitle", description: "Download subtitle content by file ID. Downloads in original format with force_download=true by default for direct file download.", inputSchema: { type: "object", properties: { file_id: { type: "number", description: "File ID from search results (found in files array of subtitle results)" }, file_name: { type: "string", description: "Desired file name for the downloaded subtitle" }, in_fps: { type: "number", description: "Input FPS for subtitle conversion (must use with out_fps)" }, out_fps: { type: "number", description: "Output FPS for subtitle conversion (must use with in_fps)" }, timeshift: { type: "number", description: "Time shift in seconds to add/remove (e.g. 2.5 or -1)" }, force_download: { type: "boolean", description: "Set subtitle file headers to 'application/force-download' for direct file download (default: true)" }, user_api_key: { type: "string", description: "Your OpenSubtitles API key for authenticated downloads" }, username: { type: "string", description: "OpenSubtitles.com username (alternative to API key)" }, password: { type: "string", description: "OpenSubtitles.com password (use with username)" } }, required: ["file_id"], additionalProperties: false } },
• src/server.ts:341-343 (registration)

  Handler dispatch in the server's handleToolCall method that routes calls to the downloadSubtitle function.
  case "download_subtitle": console.error("DEBUG: Calling downloadSubtitle"); return await downloadSubtitle(args);
• src/server.ts:4-4 (helper)

  Import statement that brings the downloadSubtitle handler into the server module.
  import { downloadSubtitle } from "./tools/download-subtitle.js";