内容
# OpenSubtitles MCP 服务器
OpenSubtitles API 集成的高级 MCP（模型上下文协议）服务器，支持字幕搜索和下载功能，采用 Freemium 模式，并使用 Kong 网关在 api.opensubtitles.com 上进行所有 API 管理。
## 功能特点
- **全面搜索**：使用所有 OpenSubtitles API 参数（标题、IMDB ID、TMDB ID、文件哈希等）搜索字幕
- **多种下载格式**：支持 SRT、ASS 和 VTT 字幕格式
- **文件哈希计算**：计算 OpenSubtitles 哈希以实现精确的电影文件匹配
- **速率限制**：与 Kong 网关集成以实现适当的速率限制
- **Freemium 模式**：无限搜索，下载受 API 密钥状态限制
## 安装与使用
OpenSubtitles MCP 服务器支持 **三种模式**：
- **HTTP 模式**：适用于 n8n 工作流、浏览器访问和 HTTP 集成
- **标准输入模式（本地）**：适用于 Claude Desktop 集成
- **标准输入模式（远程）**：连接到托管服务器 mcp.opensubtitles.com
### 1. HTTP 模式（推荐用于服务器部署）
在端口 1620 上作为 Web 服务器运行：
```bash
# 安装依赖
npm install
npm run build
# 启动 HTTP 服务器
npm start
# 或
PORT=1620 MCP_MODE=http node dist/index.js
```
**访问点：**
- **健康检查：** `http://localhost:1620/health`
- **API 信息：** `http://localhost:1620/`
- **Web 界面：** `http://localhost:1620/web`（浏览器 UI - 无需 Node.js！）
- **直接 API：** `http://localhost:1620/proxy`（POST 请求）
- **工具列表：** `http://localhost:1620/tools`（模式发现）
- **MCP 端点：** `http://localhost:1620/sse`（服务器发送事件）
### 2. 标准输入模式（适用于 Claude Desktop）
#### 快速入门
```bash
npx @opensubtitles/mcp-server
```
#### 通过 mcp-get 安装
```bash
npx @michaellatman/mcp-get@latest install @opensubtitles/mcp-server
```
#### Claude 代码集成
对于 `claude-code` 环境，您可以使用 `claude mcp add-json` 命令添加服务器：
```bash
claude mcp add-json "opensubtitles" '{"command":"npx","args":["-y","@opensubtitles/mcp-server@latest"],"env":{"MCP_MODE":"stdio","LOG_LEVEL":"info"},"disabled":false}'
```
#### Claude Desktop 集成 - 本地模式
添加到您的 Claude Desktop 配置：
```json
{
"mcpServers": {
"opensubtitles": {
"command": "npx",
"args": ["-y", "@opensubtitles/mcp-server"],
"env": {
"MCP_MODE": "stdio",
"OPENSUBTITLES_USER_KEY": "your_api_key_here"
}
}
}
}
```
#### Claude Desktop 集成 - 远程模式
连接到托管服务器 mcp.opensubtitles.com：
```json
{
"mcpServers": {
"opensubtitles": {
"command": "npx",
"args": ["-y", "@opensubtitles/mcp-server", "remote-proxy.js"]
}
}
}
```
或使用专用远程命令：
```json
{
"mcpServers": {
"opensubtitles": {
"command": "npx",
"args": ["-y", "mcp-opensubtitles-remote"]
}
}
}
```
## MCP 工具
### 1. search_subtitles
使用综合参数支持搜索字幕：
**参数：**
- `query`（字符串）：文本搜索查询
- `imdb_id`（数字）：IMDB ID 用于精确匹配
- `tmdb_id`（数字）：TMDB ID 用于精确匹配
- `parent_imdb_id`（数字）：TV 系列的父 IMDB ID
- `parent_tmdb_id`（数字）：TV 系列的父 TMDB ID
- `season_number`（数字）：TV 集的季号
- `episode_number`（数字）：TV 集的集号
- `year`（数字）：发行年份
- `moviehash`（字符串）：OpenSubtitles 文件哈希用于精确匹配
- `moviebytesize`（数字）：哈希匹配的文件大小（字节）
- `languages`（字符串）：逗号分隔的语言代码（例如，'en,es,fr'）
- `machine_translated`（字符串）：包括机器翻译的字幕
- `ai_translated`（字符串）：包括 AI 翻译的字幕
- `hearing_impaired`（字符串）：包括听力障碍的字幕
- `foreign_parts_only`（字符串）：仅包括外国部分
- `trusted_sources`（字符串）：仅限于受信任的来源
- `order_by`（字符串）：排序顺序
- `order_direction`（字符串）：排序方向（asc/desc）
**示例：**
```typescript
await mcpClient.callTool("search_subtitles", {
query: "The Matrix",
year: 1999,
languages: "en"
});
```
### 2. download_subtitle
通过 ID 下载字幕内容：
**参数：**
- `subtitle_id`（字符串，必填）：搜索结果中的字幕 ID
- `format`（字符串）：字幕格式（srt, ass, vtt）- 默认 'srt'
- `user_api_key`（字符串）：用于身份验证下载的 API 密钥
**示例：**
```typescript
await mcpClient.callTool("download_subtitle", {
subtitle_id: "123456",
format: "srt",
user_api_key: "your_api_key"
});
```
### 3. calculate_file_hash
计算本地电影文件的 OpenSubtitles 哈希：
**参数：**
- `file_path`（字符串，必填）：电影文件路径
**示例：**
```typescript
await mcpClient.callTool("calculate_file_hash", {
file_path: "/path/to/movie.mkv"
});
```
## 使用示例
### 按电影标题搜索
```typescript
await mcpClient.callTool("search_subtitles", {
query: "Inception",
year: 2010,
languages: "en"
});
```
### 按文件哈希搜索
```typescript
// 首先计算哈希
const hashResult = await mcpClient.callTool("calculate_file_hash", {
file_path: "/path/to/inception.mkv"
});
// 然后使用哈希搜索
await mcpClient.callTool("search_subtitles", {
moviehash: "8e245d9679d31e12",
moviebytesize: 12909756
});
```
### 搜索 TV 节目集
```typescript
await mcpClient.callTool("search_subtitles", {
parent_imdb_id: 944947, // Game of Thrones
season_number: 1,
episode_number: 5,
languages: "en"
});
```
## n8n 工作流集成
OpenSubtitles MCP 服务器具有 **原生 n8n MCP 客户端支持**，用于无缝的工作流自动化。通过 n8n 的内置 MCP 客户端工具直接连接到 MCP 服务器。
### 1. 在 HTTP 模式下启动服务器
首先，在 HTTP 模式下启动 MCP 服务器：
```bash
# 选项 1：使用 npm 脚本（推荐）
npm start
# 选项 2：直接命令，自定义端口
MCP_MODE=http PORT=1620 node dist/index.js
# 选项 3：使用环境变量
export MCP_MODE=http
export PORT=1620
node dist/index.js
```
服务器将在：
- **基准 URL**：`http://localhost:1620`
- **健康检查**：`http://localhost:1620/health`
- **MCP 端点**：`http://localhost:1620/message`（可流式 HTTP）
- **强制 JSON**：`http://localhost:1620/json`（纯 JSON，用于调试）
- **调试信息**：`http://localhost:1620/debug`（服务器诊断）
- **旧版 MCP**：`http://localhost:1620/sse`（服务器发送事件）
### 2. n8n MCP 客户端配置
#### 使用 n8n 原生 MCP 客户端
配置 n8n MCP 客户端工具节点：
- **服务器 URL**：`http://localhost:1620/message`（或您的服务器 URL）
- **传输**：HTTP 流式
- **协议**：模型上下文协议（MCP）
#### 搜索字幕与 MCP 客户端
配置 MCP 客户端节点，参数如下：
```json
{
"tool": "search_subtitles",
"arguments": {
"query": "The Matrix",
"year": 1999,
"languages": "en"
}
}
```
#### 替代：直接 HTTP 请求
对于手动 HTTP 集成，请使用 HTTP 请求节点：
```json
{
"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"
}
}
}
}
```
#### 使用 MCP 客户端下载字幕
```json
{
"tool": "download_subtitle",
"arguments": {
"file_id": 123456,
"user_api_key": "{{ $env.OPENSUBTITLES_API_KEY }}"
}
}
```
#### 使用 MCP 客户端计算文件哈希
```json
{
"tool": "calculate_file_hash",
"arguments": {
"file_path": "/path/to/movie.mkv"
}
}
```
### 3. n8n 工作流示例
#### 基本搜索工作流
1. **MCP 客户端工具**：使用电影标题搜索字幕
2. **代码节点**：解析搜索结果并提取文件 ID
3. **MCP 客户端工具**：下载最佳匹配的字幕
4. **文件系统节点**：将字幕保存到磁盘
#### 自动处理工作流
1. **文件触发器**：监视文件夹中的新电影文件
2. **MCP 客户端工具**：计算文件哈希
3. **MCP 客户端工具**：使用哈希搜索字幕以实现精确匹配
4. **条件节点**：检查是否找到字幕
5. **MCP 客户端工具**：如果找到，下载字幕
6. **文件系统节点**：将字幕保存到电影文件旁边
#### 原生 MCP 集成的优势
- **自动发现**：工具通过 MCP 协议自动发现
- **类型安全性**：工具参数的完整模式验证
- **错误处理**：正确的 MCP 错误响应
- **工具文档**：内联帮助和参数描述
- **JSON 兼容性**：为 n8n 客户端提供自动纯 JSON 响应
- **调试支持**：用于故障排除的内置调试端点
#### 故障排除 n8n 集成
如果遇到 JSON 解析错误：
1. **尝试强制 JSON 端点**：使用 `http://localhost:1620/json` 代替 `/message`
2. **检查调试信息**：访问 `http://localhost:1620/debug` 以验证服务器状态
3. **验证用户代理**：服务器自动检测 n8n 客户端（节点，n8n，langchain，mcpClientTool）
4. **检查日志**：查找“Sending plain JSON response for n8n compatibility” 消息
### 4. n8n 环境变量
在您的 n8n 实例中设置以下环境变量：
```bash
# OpenSubtitles API 密钥（可选但推荐）
OPENSUBTITLES_API_KEY=your_api_key_here
# MCP 服务器 URL（如果在不同主机/端口上运行）
MCP_SERVER_URL=http://localhost:1620
```
### 5. 响应格式
所有 n8n HTTP 请求都将接收 JSON-RPC 2.0 响应：
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "搜索结果或下载数据..."
}
]
}
}
```
### 6. n8n 中的错误处理
添加错误处理节点以捕获常见问题：
- **速率限制（429）**：延迟后重试或通知用户获取 API 密钥
- **无效 API 密钥（401）**：提醒管理员检查 API 密钥
- **网络错误**：重试机制或替代端点
- **文件未找到**：跳过处理或记录错误
### 7. 生产部署
用于生产 n8n 工作流：
```bash
# 以后台服务运行 MCP 服务器
nohup MCP_MODE=http PORT=1620 node dist/index.js > mcp-server.log 2>&1 &
# 或使用 PM2 进行进程管理
pm2 start dist/index.js --name "opensubtitles-mcp" -- --env MCP_MODE=http PORT=1620
# 或使用 Docker
docker run -d -p 1620:1620 -e MCP_MODE=http opensubtitles-mcp-server
```
此集成允许您在 n8n 工作流中自动执行字幕操作，非常适合媒体处理管道、批量字幕下载或自动电影库管理。
## Web 浏览器界面
对于不想安装 Node.js 或配置 MCP 的用户，我们提供了一个 **完整的 Web 界面**：
### 访问
- **网址**：`http://mcp.opensubtitles.com/web`
- **要求**：任何现代 Web 浏览器
- **无需安装**：无需设置即可立即使用
### 功能
- **🔍 搜索字幕**：按标题、年份、IMDB ID、语言搜索字幕
- **💾 下载字幕**：从搜索结果中按文件 ID 下载字幕
- **🔢 计算哈希**：为电影文件生成 OpenSubtitles 哈希
- **📊 实时结果**：具有格式化结果的即时反馈
- **🎯 用户友好**：具有加载状态和错误处理的干净界面
### 直接 HTTP API
对于开发者和自动化：
```bash
# 搜索字幕
curl -X POST http://mcp.opensubtitles.com/proxy \
-H "Content-Type: application/json" \
-d '{"tool": "search_subtitles", "arguments": {"query": "Matrix", "year": 1999}}'
# 下载字幕
curl -X POST http://mcp.opensubtitles.com/proxy \
-H "Content-Type: application/json" \
-d '{"tool": "download_subtitle", "arguments": {"file_id": 123456}}'
# 列出可用工具
curl http://mcp.opensubtitles.com/tools
```
## 速率限制和 API 密钥
### 匿名使用
- **搜索**：无限
- **下载**：0/天（Kong 强制执行）
### 使用 OpenSubtitles API 密钥
- **搜索**：无限
- **下载**：基于您的 OpenSubtitles 账户配额
### 获取 API 密钥
1. 在 [OpenSubtitles.com](https://www.opensubtitles.com/api) 注册
2. 获取您的免费 API 密钥
3. 设置 `OPENSUBTITLES_USER_KEY` 环境变量或在工具调用中传递它
## 开发
### 前提条件
- Node.js 18.0.0 或更高
- TypeScript
### 设置
```bash
git clone <仓库>
cd mcp-opensubtitles
npm install
```
### 构建
```bash
npm run build
```
### 开发命令
```bash
# HTTP 模式（Web 服务器）
npm run dev # 构建并在端口 1620 运行 HTTP 服务器
npm start # 运行构建的 HTTP 服务器
# 标准输入模式（Claude Desktop）
npm run dev:stdio # 构建并运行标准输入模式
npm start:stdio # 运行构建的标准输入模式
# 带有自动重建的开发
npm run watch
```
### 测试
```bash
# HTTP 模式测试
curl http://localhost:1620/health # 健康检查
curl http://localhost:1620/ # API 信息
# 标准输入模式测试
npm test # 运行评估测试
npm run inspector # 使用 MCP 检视器（标准输入模式）
# MCP 评估测试
npx mcp-eval evals/evals.ts dist/index.js
```
### 环境变量
```bash
OPENSUBTITLES_API_BASE=https://api.opensubtitles.com # 默认 Kong 网关
NODE_ENV=production
PORT=1620
OPENSUBTITLES_USER_KEY=your_api_key_here # 可选
```
## 架构
服务器使用以下组件的清洁架构：
- **MCP 服务器核心** (`src/server.ts`)：主要 MCP 协议实现
- **Kong API 客户端** (`src/api-client.ts`)：Kong 网关通信的 HTTP 客户端
- **工具** (`src/tools/`)：单个工具实现
- **实用程序** (`src/utils/`)：哈希计算的帮助函数
所有 API 请求都通过 `api.opensubtitles.com` 上的 Kong 网关：
- **速率限制强制执行**
- **API 密钥验证**
- **请求路由到 OpenSubtitles API**
- **错误处理和响应
## 错误处理
服务器为常见场景提供有用的错误消息：
- **速率限制超过**：“下载限额达到。在 opensubtitles.com/api 获取您的免费 API 密钥”
- **无效 API 密钥**：“无效的 API 密钥。请检查您的 OpenSubtitles API 密钥”
- **文件未找到**：清晰的文件路径验证消息
- **网络错误**：描述性网络连接消息
## 贡献
1. **Fork 仓库**
2. **创建功能分支**
3. **进行更改**
4. **添加测试**
5. **提交拉取请求**
## 许可证
MIT 许可证 - 参见 LICENSE 文件以获取详细信息
## 支持
- **问题**：在 GitHub 上报告错误和功能请求
- **API 文档**：[OpenSubtitles API 文档](https://opensubtitles.stoplight.io/docs/opensubtitles-api/e3750fd63a100-getting-started)
- **MCP 协议**：[Model Context Protocol 文档](https://modelcontextprotocol.io/)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器