MCP SubMatcher

MCP SubMatcher is a local server that automatically renames subtitle files to match video files using a statistical token-based matching algorithm. This makes it easy to load subtitles correctly even when release group tags, resolutions, or other noise in file names would otherwise hinder automatic matching.

How to use

You work with an MCP client to scan your media directories, preview matching results, and rename subtitles when you are ready. The workflow is practical and interactive: first scan a directory to detect videos and subtitles, then preview the best subtitle matches, and finally perform the actual rename operation if you are satisfied.

How to install

Prerequisites you need before installing: Python 3.10 or later, the uv package manager, and an MCP client such as Claude Desktop.

curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# or macOS users can also install via Homebrew if desired
brew install uv

Additional setup and advanced configuration

You configure the MCP client to load a local MCP SubMatcher instance hosted by uvx or uv. This enables automatic installation and updating of the server directly from its source repository.

// macOS or Windows Claude Desktop configuration path example
{
  "mcpServers": {
    "submatcher": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sienyaa/mcp-submatcher",
        "mcp-submatcher"
      ]
    }
  }
}

Configuration notes for Claude Desktop (example)

Add an MCP server entry that uses uvx to install and run the latest MCP SubMatcher from the repository. This approach requires no manual cloning or dependency installation.

{
  "mcpServers": {
    "submatcher": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sienyaa/mcp-submatcher",
        "mcp-submatcher"
      ]
    }
  }
}

Quick start example with Claude Desktop

After setup, you can interact with Claude to perform these steps: scan a directory for videos and subtitles, preview matching results, and rename subtitles when ready.

你：请扫描 /Users/username/Videos/TVShows 目录中的视频和字幕文件
Claude：[自动调用 scan_media_files 工具]
扫描完成，找到 5 个视频文件和 6 个字幕文件。

你：请预览这个目录中的字幕匹配结果
Claude：[自动调用 preview_matching 工具]
匹配结果预览：
1. Breaking.Bad.S01E01.1080p.BluRay.x264-SPARKS.mkv
   - 匹配字幕: Breaking.Bad.S01E01.chs&eng.ass (评分: 280.0)
2. Breaking.Bad.S01E02.720p.WEB-DL.DDP5.1.H.264-NTb.mkv
   - 匹配字幕: Breaking.Bad.S01E02.cht&eng.srt (评分: 270.0)

你：看起来不错，请执行实际重命名
Claude：[自动调用 rename_subtitles 工具]
重命名完成：
- Breaking.Bad.S01E01.chs&eng.ass → Breaking.Bad.S01E01.1080p.BluRay.x264-SPARKS.ass
- Breaking.Bad.S01E02.cht&eng.srt → Breaking.Bad.S01E02.720p.WEB-DL.DDP5.1.H.264-NTb.srt

Security and safety features

The server includes a dry-run mode, a confirmation mechanism, and automatic backups to prevent accidental changes. You can enable or disable these features as needed and review actions before they affect your files.

Troubleshooting and tips

If you cannot find a good subtitle match, try lowering the matching score threshold or inspecting how tokens are extracted from filenames. Ensure your subtitle filenames include season and episode identifiers (for example, S01E01) to improve matching accuracy.

# Example: adjust minimum score threshold
# This value should be set in the configuration file or via MCP tooling

Best practices

Use preview mode first to verify results before renaming, enable backups to protect original subtitle files, and keep a clear backup directory for quick restoration if needed.

Notes on usage with multiple series in one folder

The matching algorithm clusters tokens to distinguish multiple series that may be mixed in a single directory, allowing correct subtitle associations even when several shows share a common folder.

Available tools

scan_media_files

Scans a specified directory to identify video and subtitle files and returns structured information about found items.

preview_matching

Analyzes the directory to compare videos with subtitles and presents a scoring-based preview of the best matches without making changes.

rename_subtitles

Renames selected subtitle files to align with their corresponding video filenames, with an option for a dry-run.

get_config_value

Retrieves a value from the current configuration given a path.

set_config_value

Sets a value in the current configuration and optionally backs up the previous config.

get_config_summary

Returns a summary of the current configuration state including weights and safety settings.