OpenSubtitles MCP Server

A TypeScript/Node.js-based MCP (Model Context Protocol) server for OpenSubtitles API integration. This server provides subtitle search and download functionality with a freemium model, using the Kong gateway at api.opensubtitles.com for all API management.

Features

• Comprehensive Search: Search subtitles using all OpenSubtitles API parameters (title, IMDB ID, TMDB ID, file hash, etc.)
• Multiple Download Formats: Support for SRT, ASS, and VTT subtitle formats
• File Hash Calculation: Calculate OpenSubtitles hash for exact movie file matching
• Rate Limiting: Integrated with Kong gateway for proper rate limiting
• Freemium Model: Unlimited search, downloads limited by API key status

Installation & Usage

The OpenSubtitles MCP Server supports three modes:

• HTTP Mode: Web server for n8n workflows, browser access, and HTTP integrations
• Stdio Mode (Local): Run locally for Claude Desktop integration
• Stdio Mode (Remote): Connect to hosted server at mcp.opensubtitles.com

1. HTTP Mode (Recommended for Server Deployment)

Run as a web server on port 1620:

# Install dependencies
npm install
npm run build

# Start HTTP server
npm start
# or
PORT=1620 MCP_MODE=http node dist/index.js

Access points:

• Health Check: http://localhost:1620/health
• API Info: http://localhost:1620/
• Web Interface: http://localhost:1620/web (Browser UI - No Node.js required!)
• Direct API: http://localhost:1620/proxy (POST requests)
• Tools List: http://localhost:1620/tools (Schema discovery)
• MCP Endpoint: http://localhost:1620/sse (Server-Sent Events)

2. Stdio Mode (For Claude Desktop)

Quick Start with npx

npx @opensubtitles/mcp-server

Install via mcp-get

npx @michaellatman/mcp-get@latest install @opensubtitles/mcp-server

Claude Code Integration

For claude-code environments, you can add the server using the claude mcp add-json command:

claude mcp add-json "opensubtitles" '{"command":"npx","args":["-y","@opensubtitles/mcp-server@latest"],"env":{"MCP_MODE":"stdio","LOG_LEVEL":"info"},"disabled":false}'

Claude Desktop Integration - Local Mode

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "opensubtitles": {
      "command": "npx",
      "args": ["-y", "@opensubtitles/mcp-server"],
      "env": {
        "MCP_MODE": "stdio",
        "OPENSUBTITLES_USER_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop Integration - Remote Mode

Connect to the hosted server at mcp.opensubtitles.com:

{
  "mcpServers": {
    "opensubtitles": {
      "command": "npx",
      "args": ["-y", "@opensubtitles/mcp-server", "remote-proxy.js"]
    }
  }
}

Or using the dedicated remote command:

{
  "mcpServers": {
    "opensubtitles": {
      "command": "npx",
      "args": ["-y", "mcp-opensubtitles-remote"]
    }
  }
}

MCP Tools

1. search_subtitles

Search for subtitles with comprehensive parameter support:

Parameters:

• query (string): Text search query
• imdb_id (number): IMDB ID for exact matching
• tmdb_id (number): TMDB ID for exact matching
• parent_imdb_id (number): Parent IMDB ID for TV series
• parent_tmdb_id (number): Parent TMDB ID for TV series
• season_number (number): Season number for TV episodes
• episode_number (number): Episode number for TV episodes
• year (number): Release year
• moviehash (string): OpenSubtitles file hash for exact matching
• moviebytesize (number): File size in bytes for hash matching
• languages (string): Comma-separated language codes (e.g., 'en,es,fr')
• machine_translated (string): Include machine translated subtitles
• ai_translated (string): Include AI translated subtitles
• hearing_impaired (string): Include hearing impaired subtitles
• foreign_parts_only (string): Include foreign parts only
• trusted_sources (string): Only trusted sources
• order_by (string): Sort order
• order_direction (string): Sort direction (asc/desc)

Example:

await mcpClient.callTool("search_subtitles", {
  query: "The Matrix",
  year: 1999,
  languages: "en"
});

2. download_subtitle

Download subtitle content by ID:

Parameters:

• subtitle_id (string, required): Subtitle ID from search results
• format (string): Subtitle format (srt, ass, vtt) - defaults to 'srt'
• user_api_key (string): Optional user API key for authenticated downloads

Example:

await mcpClient.callTool("download_subtitle", {
  subtitle_id: "123456",
  format: "srt",
  user_api_key: "your_api_key"
});

3. calculate_file_hash

Calculate OpenSubtitles hash for local movie files:

Parameters:

• file_path (string, required): Path to the movie file

Example:

await mcpClient.callTool("calculate_file_hash", {
  file_path: "/path/to/movie.mkv"
});

Usage Examples

Search by Movie Title

await mcpClient.callTool("search_subtitles", {
  query: "Inception",
  year: 2010,
  languages: "en"
});

Search by File Hash

// First calculate the hash
const hashResult = await mcpClient.callTool("calculate_file_hash", {
  file_path: "/path/to/inception.mkv"
});

// Then search using the hash
await mcpClient.callTool("search_subtitles", {
  moviehash: "8e245d9679d31e12",
  moviebytesize: 12909756
});

Search TV Show Episodes

await mcpClient.callTool("search_subtitles", {
  parent_imdb_id: 944947, // Game of Thrones
  season_number: 1,
  episode_number: 5,
  languages: "en"
});

n8n Workflow Integration

The OpenSubtitles MCP Server has native n8n MCP client support for seamless workflow automation. Connect directly to the MCP server using n8n's built-in MCP client tools.

1. Start Server in HTTP Mode

First, start the MCP server in HTTP mode:

# Option 1: Use npm script (recommended)
npm start

# Option 2: Direct command with custom port
MCP_MODE=http PORT=1620 node dist/index.js

# Option 3: Using environment variables
export MCP_MODE=http
export PORT=1620
node dist/index.js

The server will be available at:

• Base URL: http://localhost:1620
• Health Check: http://localhost:1620/health
• MCP Endpoint: http://localhost:1620/message (Streamable HTTP)
• Force JSON: http://localhost:1620/json (Plain JSON for debugging)
• Debug Info: http://localhost:1620/debug (Server diagnostics)
• Legacy MCP: http://localhost:1620/sse (Server-Sent Events)

2. n8n MCP Client Configuration

Using n8n Native MCP Client

Configure the n8n MCP Client Tool node:

• Server URL: http://localhost:1620/message (or your server URL)
• Transport: HTTP Streamable
• Protocol: Model Context Protocol (MCP)

Search Subtitles with MCP Client

Configure the MCP Client node with these parameters:

{
  "tool": "search_subtitles",
  "arguments": {
    "query": "The Matrix", 
    "year": 1999,
    "languages": "en"
  }
}

Alternative: Direct HTTP Request

For manual HTTP integration, use HTTP Request node:

{
  "method": "POST",
  "url": "http://localhost:1620/message",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_subtitles",
      "arguments": {
        "query": "The Matrix",
        "year": 1999,
        "languages": "en"
      }
    }
  }
}

Download Subtitle with MCP Client

{
  "tool": "download_subtitle",
  "arguments": {
    "file_id": 123456,
    "user_api_key": "{{ $env.OPENSUBTITLES_API_KEY }}"
  }
}

Calculate File Hash with MCP Client

{
  "tool": "calculate_file_hash",
  "arguments": {
    "file_path": "/path/to/movie.mkv"
  }
}

3. n8n Workflow Examples

Basic Search Workflow

1. MCP Client Tool: Search for subtitles using movie title
2. Code Node: Parse search results and extract file IDs
3. MCP Client Tool: Download best matching subtitle
4. File System Node: Save subtitle to disk

Automated Processing Workflow

1. File Trigger: Monitor folder for new movie files
2. MCP Client Tool: Calculate file hash
3. MCP Client Tool: Search subtitles by hash for exact match
4. Conditional Node: Check if subtitles found
5. MCP Client Tool: Download subtitle if found
6. File System Node: Save subtitle next to movie file

Benefits of Native MCP Integration

• Auto-discovery: Tools are automatically discovered via MCP protocol
• Type Safety: Full schema validation for tool arguments
• Error Handling: Proper MCP error responses
• Tool Documentation: Inline help and parameter descriptions
• JSON Compatibility: Automatic plain JSON responses for n8n clients
• Debug Support: Built-in debugging endpoints for troubleshooting

Troubleshooting n8n Integration

If you encounter JSON parsing errors:

1. Try Force JSON Endpoint: Use http://localhost:1620/json instead of /message
2. Check Debug Info: Visit http://localhost:1620/debug to verify server status
3. Verify User-Agent: Server auto-detects n8n clients (node, n8n, langchain, mcpClientTool)
4. Check Logs: Look for "Sending plain JSON response for n8n compatibility" messages

4. Environment Variables for n8n

Set these environment variables in your n8n instance:

# OpenSubtitles API Key (optional but recommended)
OPENSUBTITLES_API_KEY=your_api_key_here

# MCP Server URL (if running on different host/port)
MCP_SERVER_URL=http://localhost:1620

5. Response Format

All n8n HTTP requests will receive JSON-RPC 2.0 responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Search results or download data..."
      }
    ]
  }
}

6. Error Handling i

---