语音转写_mcp

Name: 语音转写_mcp
Author: Omarbadran37

作者：Omarbadran372 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

转录 MCP 服务器

一个全面的模型上下文协议（MCP）服务器，提供基于AI的转录工具，用于YouTube视频和播客，使用YouTube Transcript API和Google Gemini Flash 2.5。

功能

YouTube 文字提取 - 从YouTube视频中提取带有时间戳的文字
播客RSS发现 - 通过名称在多个来源中查找播客RSS源
播客集数转录 - 下载并转录音频，包括说话者区分
自动格式化文字 - 自动格式化文字，包括说话者检测、章节标题和填充词移除
独立文字格式化 - 将任何原始文字格式化为专业、可发布的文档
智能缓存 - 使用哈希缓存避免冗余API调用
灵活的输出格式 - 支持Markdown（人类可读）和JSON（机器可读）
进度跟踪 - 长时间运行操作的实时进度更新

安装与设置

先决条件

Python 3.8 或更高版本
Google Gemini API密钥（用于播客转录）
macOS、Linux 或 Windows

快速设置（推荐用于Claude桌面）

按照以下步骤设置MCP服务器以供Claude桌面使用：

cd transcribe_mcp_server

创建Python虚拟环境：

python3 -m venv mcp_env

激活虚拟环境：

macOS/Linux:

source mcp_env/bin/activate

Windows:

mcp_env\Scripts\activate

安装依赖项：

pip install -r requirements.txt

获取Google Gemini API密钥：
- 访问 https://aistudio.google.com/app/apikey
- 创建新的API密钥
- 复制完整的密钥（不带空格）
创建 .env 文件：

echo "GOOGLE_API_KEY=your-api-key-here" > .env

替换 your-api-key-here 为第5步中的实际API密钥。

测试设置：

python -m py_compile transcribe_mcp.py

如果没有任何错误出现，则设置完成！

使用方法

运行服务器

MCP服务器作为基于stdio的服务运行：

python transcribe_mcp.py

注意：MCP服务器设计为与MCP客户端（如Claude桌面）一起使用。直接运行服务器会导致它等待stdio输入。

Claude桌面配置

这是最重要的一步。仔细遵循这些指令以避免常见错误。

第1步：创建配置文件

打开Claude桌面配置文件：

macOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

第2步：添加MCP服务器配置

重要：使用虚拟环境Python的绝对路径，而不是系统Python。

替换 /Users/YOUR-USERNAME/path/to/transcribe_mcp 为你的实际项目路径，然后添加：

{
  "mcpServers": {
    "transcribe": {
      "command": "/Users/YOUR-USERNAME/path/to/transcribe_mcp/transcribe_mcp_server/mcp_env/bin/python3",
      "args": ["/Users/YOUR-USERNAME/path/to/transcribe_mcp/transcribe_mcp_server/transcribe_mcp.py"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

示例（macOS）：

{
  "mcpServers": {
    "transcribe": {
      "command": "/Users/omar/Desktop/transcribe_mcp/transcribe_mcp_server/mcp_env/bin/python3",
      "args": ["/Users/omar/Desktop/transcribe_mcp/transcribe_mcp_server/transcribe_mcp.py"],
      "env": {
        "GOOGLE_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

远程MCP服务器（云运行）

MCP服务器也可以部署到Google Cloud Run以进行远程访问。

部署服务URL

https://transcribe-mcp-515118417864.us-central1.run.app

方案1：公开访问（最简单）

使服务公开可访问：

gcloud run services update transcribe-mcp \
  --region us-central1 \
  --allow-unauthenticated

然后配置Claude桌面：

{
  "mcpServers": {
    "transcribe-remote": {
      "url": "https://transcribe-mcp-515118417864.us-central1.run.app/sse"
    }
  }
}

方案2：认证访问（更安全）

安装mcp-remote代理：

npm install -g @anthropic/mcp-remote

使用认证配置Claude桌面：

{
  "mcpServers": {
    "transcribe-remote": {
      "command": "mcp-remote",
      "args": [
        "https://transcribe-mcp-515118417864.us-central1.run.app/sse",
        "--header", "Authorization: Bearer $(gcloud auth print-identity-token)"
      ]
    }
  }
}

测试远程服务器

# 健康检查（带认证）
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://transcribe-mcp-515118417864.us-central1.run.app/health

# YouTube文字
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" \
  https://transcribe-mcp-515118417864.us-central1.run.app/api/youtube/transcript \
  -d '{"video_url_or_id": "dQw4w9WgXcQ"}'

参见docs/setup/cloud-run-deploy.md以获取完整的部署说明。

参见docs/setup/webapp-integration.md以了解如何使用Supabase认证将MCP集成到您的Web应用中。

第3步：找到您的绝对路径

如果您不知道您的绝对路径，请在终端中运行：

cd /Users/YOUR-USERNAME/Desktop/transcribe_mcp/transcribe_mcp_server
pwd

这将打印您的绝对路径。在上面的配置中使用它。

第4步：重新启动Claude桌面

重要：完全关闭Claude桌面并重新打开。

Claude桌面需要重启以加载MCP服务器配置。

第5步：验证是否工作

在Claude桌面中，您应该看到一个🔌图标，表示MCP工具已加载。尝试询问：

“获取此YouTube视频的文字：https://youtube.com/watch?v=i43kYARbSGM”

如果成功，您就完成了！🎉

解决Claude桌面设置问题

错误：“spawn python ENOENT”

原因：使用python或python3而不是完整的虚拟环境路径
解决方法：使用绝对路径：/Users/YOUR-USERNAME/.../mcp_env/bin/python3

错误：“youtube-transcript-api未安装”

原因：虚拟环境中未安装依赖项

解决方法：

cd transcribe_mcp_server
source mcp_env/bin/activate
pip install -r requirements.txt

错误：“无效的API密钥”

原因：API密钥未设置或不正确
解决方法：
1. 从 https://aistudio.google.com/app/apikey 获取新密钥
2. 更新 claude_desktop_config.json 中的 GOOGLE_API_KEY
3. 重新启动Claude桌面

工具未显示在Claude桌面中

原因：配置文件未找到或存在语法错误
解决方法：
1. 检查文件是否存在于：~/Library/Application\ Support/Claude/claude_desktop_config.json
2. 验证JSON语法（如有疑问，使用 https://jsonlint.com）
3. 重新启动Claude桌面
4. 检查Claude桌面设置中的配置文件图标

仍然无法工作？

检查虚拟环境是否成功创建：

ls -la /Users/YOUR-USERNAME/path/to/transcribe_mcp/transcribe_mcp_server/mcp_env/bin/python3

如果该文件不存在，则虚拟环境未创建。返回设置步骤2并创建它：

cd transcribe_mcp_server
python3 -m venv mcp_env
source mcp_env/bin/activate
pip install -r requirements.txt

可用工具（总计12个：7个标准 + 5个批处理）

MCP服务器提供了12个强大的转录工具，组织成标准转录和批处理类别。

标准工具（7个）

1. `transcribe_get_youtube_transcript`

从YouTube视频中提取文字，可通过URL或视频ID，可选自动格式化。

参数：

video_url_or_id（必需） - YouTube URL或11位视频ID
include_timestamps（默认：true） - 包含时间信息
auto_format（默认：false） - 自动格式化为专业文档
clean_filler_words（默认：true） - 当auto_format=true时移除填充词
response_format（默认："markdown"） - 输出格式："markdown"或"json"
use_cache（默认：true） - 在获取之前检查缓存

示例：

原始文字：

video_url_or_id: "dQw4w9WgXcQ"
include_timestamps: true
response_format: "markdown"

专业格式化的文字：

video_url_or_id: "dQw4w9WgXcQ"
auto_format: true
clean_filler_words: true
response_format: "markdown"

输出：原始文字或带有说话者、章节和时间戳的专业文档

2. `transcribe_find_podcast_rss`

通过名称查找播客的RSS源URL。

搜索策略：

Podcastindex API
Apple Podcasts API
常见托管平台（Megaphone、Anchor、Podbean）

参数：

podcast_name（必需） - 要搜索的播客名称
response_format（默认："markdown"） - 输出格式

示例：

podcast_name: "Lex Fridman Podcast"

输出：RSS源URL和播客元数据

3. `transcribe_parse_rss_feed`

解析播客RSS源并列出可用的集数。

参数：

rss_url（必需） - RSS源URL
max_episodes（默认：10，最大：50） - 返回的最大集数
response_format（默认："markdown"） - 输出格式

示例：

rss_url: "https://feeds.megaphone.fm/lexfridmanpodcast"
max_episodes: 5

输出：带有标题、音频URL、日期和持续时间的集数列表

4. `transcribe_podcast_episode`

使用Google Gemini下载并转录音频，可选自动格式化。

参数：

audio_url（必需） - 直接音频文件URL（.mp3、.m4a、.wav）
episode_title（可选） - 元数据中的集数标题
include_timestamps（默认：true） - 包含时间戳
speaker_diarization（默认：true） - 识别不同的说话者
auto_format（默认：false） - 自动格式化为专业文档
clean_filler_words（默认：true） - 当auto_format=true时移除填充词
save_to_disk（默认：true） - 将文字保存到./transcripts/
use_cache（默认：true） - 在处理之前检查缓存
response_format（默认："markdown"） - 输出格式

示例：

原始文字：

audio_url: "https://example.com/podcast/episode.mp3"
episode_title: "Episode 1: Introduction"
speaker_diarization: true

专业格式化的文字：

audio_url: "https://example.com/podcast/episode.mp3"
episode_title: "Episode  1: Introduction"
speaker_diarization: true
auto_format: true
clean_filler_words: true

输出：原始文字或带有说话者标签、章节和时间戳的专业文档

注意事项：

需要Google Gemini API密钥
处理时间：取决于音频长度，大约1-5分钟
大文件（>20MB）自动使用Gemini文件API
根据Gemini API定价收费（每小时音频约$0.05-0.10）

5. `transcribe_get_cached_transcript`

通过缓存键检索先前缓存的文字。

参数：

cache_key（必需） - 来自先前转录的32位MD5哈希
response_format（默认："markdown"） - 输出格式

示例：

cache_key: "abc123def456..."

输出：带有元数据的缓存文字

6. `transcribe_list_cache`

列出所有缓存的文字。

参数：

limit（默认：20，最大：100） - 返回的最大结果数
response_format（默认："markdown"） - 输出格式

输出：带有缓存键、日期和来源的缓存文字列表

7. `transcribe_format_transcript`

格式化并增强任何原始文字，使其成为专业、可发布的文档。

参数：

raw_transcript（必需） - 要格式化的原始文字（至少10个字符）
title（默认："访谈文字"） - 格式化文字的标题
include_timestamps（默认：true） - 在输出中包含时间戳
clean_filler_words（默认：true） - 移除填充词（"um"、"uh"、"like"等）
auto_detect_speakers（默认：true） - 自动检测说话者姓名
detect_sections（默认：true） - 自动创建章节标题
response_format（默认："markdown"） - 输出格式："markdown"或"json"

示例：

raw_transcript: "[全文在这里...]"
title: "专家访谈"
include_timestamps: true
clean_filler_words: true
auto_detect_speakers: true
detect_sections: true
response_format: "markdown"

输出：带有说话者、章节、对话要点和时间戳的专业文档

特性：

自动从标签中检测说话者姓名
智能章节标题创建
移除填充词："um"、"uh"、"er"、"ah"、"hmm"、"like"、"你知道"、"基本上"、"实际上"
专业对话要点格式
加粗说话者姓名标识
时间戳保留为[MM:SS]格式
语法和间距清理

处理时间：2-5秒（无API调用，仅本地处理）

示例输出（Markdown）：

# 专家访谈

**说话者**：Alice, Bob
**格式**：访谈文字

---

## **引言**

* [00:00] **Alice**：欢迎来到节目...
* **Bob**：感谢邀请...

## **主要讨论**

* [05:30] **Alice**：让我们谈谈这个话题...
* **Bob**：当然，这是我的观点...

## **结论**

* [38:45] **Alice**：感谢这次对话...

批处理工具（5个 - 成本节省50%）

批处理工具提供了批量作业的成本效益转录。当转录5个以上集数或整个播客系列时使用这些工具。批处理比标准API调用节省50%成本。

8. `transcribe_submit_batch`

提交多个播客集数的批处理转录任务。

参数：

episodes（可选） - 包含title和audio_url键的集数数组
rss_url（可选） - 或提供RSS源URL以自动解析
max_episodes（默认：50，最大：1000） - 处理的最大集数
filter_cached（默认：true） - 跳过已缓存的集数
job_name（可选） - 用于跟踪批处理任务的自定义名称
speaker_diarization（默认：true） - 启用说话者识别
include_timestamps（默认：true） - 在文字中包含时间戳
auto_format（默认：true） - 自动格式化为专业文档
clean_filler_words（默认：true） - 当auto_format=true时移除填充词
response_format（默认："markdown"） - 输出格式

示例1：通过RSS源提交：

rss_url: "https://feeds.megaphone.fm/lexfridmanpodcast"
max_episodes: 10
auto_format: true
job_name: "lex-batch-001"

示例2：通过集数列表提交：

episodes: [
  {"