MCP SubMatcher MCP Server

MCP SubMatcher

一个基于统计分词匹配算法的 MCP 服务器，能够自动将本地字幕文件重命名为与对应视频同名，解决压制组、分辨率等干扰信息导致的无法自动加载字幕的问题。

特性

• 🎯 智能匹配算法：基于文件名分词和权重系统，自动匹配视频和字幕
• 🌍 多语言支持：支持简英双语、繁英双语、简体中文、繁体中文、纯英文
• 📊 格式识别：ASS格式优先于SRT格式
• 🔧 压制组识别：识别相同的压制组给予额外加分
• 🛡️ 安全机制：演习模式、确认机制、备份功能
• ⚙️ 可配置性：完全可定制的权重和匹配规则
• 🔌 MCP 协议：通过 MCP 协议与 Claude Desktop 等 AI 客户端集成
• 📝 审计日志：自动记录所有配置变更

安装

环境要求

• Python 3.10 或更高版本
• uv - 快速 Python 包管理器
• Claude Desktop 或其他 MCP 客户端

快速安装

1. 安装 UV（如果还未安装）

curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# 或
brew install uv  # macOS

2. 配置 Claude Desktop（推荐方式）

直接在 Claude Desktop 配置文件中使用 uvx 从 GitHub 安装，无需克隆项目。

配置 MCP 客户端

Claude Desktop 配置

在 Claude Desktop 的配置文件中添加 MCP 服务器：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

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

说明：

• uvx 会自动从 GitHub 下载并运行最新版本的 MCP SubMatcher
• 无需手动克隆项目或安装依赖
• 每次启动时会自动检查并使用最新版本

高级配置（可选）

如果需要使用特定版本或本地开发版本，可以使用以下配置：

{
  "mcpServers": {
    "submatcher": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-submatcher",
        "run",
        "mcp-submatcher"
      ]
    }
  }
}

说明：

• 适用于本地开发或需要使用特定版本的情况
• 需要先克隆项目并运行 uv sync

重启 Claude Desktop

配置完成后，重启 Claude Desktop 以加载 MCP 服务器。

快速开始

配置完成后，你可以直接在 Claude Desktop 中与对话：

你：请扫描 /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

就这么简单！无需手动运行任何命令，只需与 Claude 对话即可。

工具详解

MCP SubMatcher 提供以下 6 个工具：

1. scan_media_files

扫描指定目录中的视频和字幕文件。

参数：

• directory (string, 必需): 要扫描的目录路径

对话示例：

你：请扫描 /Users/username/Videos/TVShows 目录中的视频和字幕文件

Claude：[调用 scan_media_files 工具]
扫描完成，找到 5 个视频文件和 6 个字幕文件。

输出示例：

{
  "success": true,
  "directory": "/Users/username/Videos/TVShows",
  "video_files": [
    {
      "path": "/Users/username/Videos/TVShows/Breaking.Bad.S01E01.1080p.BluRay.x264-SPARKS.mkv",
      "file_type": "video",
      "name": "Breaking.Bad.S01E01.1080p.BluRay.x264-SPARKS.mkv",
      "stem": "Breaking.Bad.S01E01.1080p.BluRay.x264-SPARKS",
      "extension": ".mkv",
      "tokens": ["breaking", "bad", "s01e01", "1080p", "bluray", "x264", "sparks"],
      "season": 1,
      "episode": 1
    }
  ],
  "subtitle_files": [
    {
      "path": "/Users/username/Videos/TVShows/Breaking.Bad.S01E01.chs&eng.ass",
      "file_type": "subtitle",
      "name": "Breaking.Bad.S01E01.chs&eng.ass",
      "stem": "Breaking.Bad.S01E01.chs&eng",
      "extension": ".ass",
      "tokens": ["breaking", "bad", "s01e01", "chs&eng"],
      "season": 1,
      "episode": 1
    }
  ],
  "video_count": 5,
  "subtitle_count": 6
}

2. preview_matching

预览字幕匹配结果（演习模式，不会实际修改文件）。

参数：

• directory (string, 必需): 要分析的目录路径

对话示例：

你：请预览 /Users/username/Videos/TVShows 目录中的字幕匹配结果

Claude：[调用 preview_matching 工具]
匹配结果预览：
1. Breaking.Bad.S01E01.1080p.BluRay.x264-SPARKS.mkv
   - 匹配字幕: Breaking.Bad.S01E01.chs&eng.ass (评分: 280.0)
   - 语言权重: 120.0
   - 格式权重: 100.0
   - 血统加分: 0.0

输出示例：

[
  {
    "video": {
      "path": "/Users/username/Videos/TVShows/Breaking.Bad.S01E01.1080p.BluRay.x264-SPARKS.mkv",
      "file_type": "video",
      "name": "Breaking.Bad.S01E01.1080p.BluRay.x264-SPARKS.mkv",
      "stem": "Breaking.Bad.S01E01.1080p.BluRay.x264-SPARKS",
      "extension": ".mkv",
      "tokens": ["breaking", "bad", "s01e01", "1080p", "bluray", "x264", "sparks"],
      "season": 1,
      "episode": 1
    },
    "subtitle": {
      "path": "/Users/username/Videos/TVShows/Breaking.Bad.S01E01.chs&eng.ass",
      "file_type": "subtitle",
      "name": "Breaking.Bad.S01E01.chs&eng.ass",
      "stem": "Breaking.Bad.S01E01.chs&eng",
      "extension": ".ass",
      "tokens": ["breaking", "bad", "s01e01", "chs&eng"],
      "season": 1,
      "episode": 1
    },
    "score": 280.0,
    "language_weight": 120.0,
    "format_weight": 100.0,
    "lineage_bonus": 0.0
  }
]

3. rename_subtitles

执行字幕重命名操作。

参数：

• directory (string, 必需): 要处理的目录路径
• confirm (boolean, 可选): 是否确认执行实际重命名（默认为 false，仅演习模式）

对话示例：

你：请重命名 /Use