内容
scribefy-mcp
[MCP](https://modelcontextprotocol.io) 服务器，用于 [Scribefy](https://scribefy.app) — 从 Claude Desktop、Cursor、Windsurf、ChatGPT 自定义 GPT 等任意其他支持 MCP 的客户端中提取 YouTube 文字记录。
> **现已上线** — 在下方一分钟内设置完成，或在 **[scribefy.app](https://scribefy.app)** 上尝试网页应用。
## 为什么
大多数 YouTube 文字记录工具都存在于浏览器扩展或一次性网页 UI 中。本项目将 Scribefy 的 API 封装成 MCP 标准，以便您的 AI 助手在用户粘贴 YouTube 链接时可以提取文字记录 — 无需手动复制粘贴，也无需单独的标签页。
## 要求
- Node 20+
- 一个 Scribefy 账户，订阅 **API + MCP** 计划（25 美元/月），即可获得 API 密钥。您可以先不输入密钥进行安装 — MCP 主机会干净地注册服务器，当您尝试使用工具时，您将收到友好的提示，然后从 [scribefy.app/dashboard](https://scribefy.app/dashboard) 添加您的密钥即可开始提取。
## 设置
### Claude Desktop
打开配置文件（`设置 → 开发者 → 编辑配置`）：
```json
{
"mcpServers": {
"scribefy": {
"command": "npx",
"args": ["-y", "scribefy-mcp"],
"env": {
"SCRIBEFY_API_KEY": "sk_live_…"
}
}
}
}
```
重启 Claude Desktop。`extract_transcript` 工具将出现在可用工具面板中。
### Cursor
`设置 → Cursor 设置 → MCP → 添加新的 MCP 服务器`：
```json
{
"scribefy": {
"command": "npx",
"args": ["-y", "scribefy-mcp"],
"env": {
"SCRIBEFY_API_KEY": "sk_live_…"
}
}
}
```
### Windsurf
`~/.codeium/windsurf/mcp_config.json`：
```json
{
"mcpServers": {
"scribefy": {
"command": "npx",
args": ["-y",fy-mcp"],
"env": {
"SCRIBEFY_API_KEY": "sk…"
}
}
}
```
### 其他任意位置支持 stdio 传输的 MCP 主机：使用 `SCRY_API_KEY` 在中启动 `npx -y scribefy-mcp`。 stdin/stdout 使用标准CP](https://modelcontextprotocol.io) JSON-RPC。
提供的工具
四个工具。（研究工具包）；只有 `extract_transcript` 需要积分。
### `extract_transcript`
提取 YouTube 视频的文字记录。
| 类型 | 必需 | 描述---|---|---|---|
| `url` | 字符串 | 是 | YouTube URL — `/watch?v=…`、`youtu.be/…` 或 `youtubeorts/…` |
lang` | 字符串 | 否CP-47 语言例如 `en`、`es`、`fr`、`zh-Hans`）。默认为 `en` |
**返回：** 包含标题、频道、时长、语言和按时间戳分割的文字记录的 Markdown。
**费用：** 1 积分（≤15 分钟）→ 8 积分（2 小时以上）。缓存的文字记录免费。
### `search_videos`
自由文本 YouTube 搜索。
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `query` | 字符串 | 是 | 搜索查询 — 与 YouTube 自己的搜索栏接受的语法相同 |
| `limit` | 数字 | 否 | 最大结果数，1-默认为 10） |
**返回：** 每个标题 / 频道 / 时长 / 浏览量 的 Markdown 列表。
**费用：** 免费。
### `get_video_metadata`
标题、频道、时长、浏览量、上传日期和字幕轨道。**不** 拉取文字记录。
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `url` | 字符串 | 是 | 完整的 YouTube URL |
**返回：** Markdown 摘要以及每个字幕轨道（作者 ✏ 或自动生成 ⚙）的列表，包含其语言代码。
**费用：** 免费功能来检查视频，然后决定是否提取，或发现有哪些字幕语言可用。
### `get_related_videos`
YouTube 的“下一个”视频推荐。
| 参数 | 类型 | 必需 | 描述 |
|---|
| `url` | 字符串 | 是 | 种子视频的完整 YouTube URL |
| `limit` | 数字 | 否 | 最大相关视频数，1-25（默认为 10） |
**返回：** 与 `search_videos` 相同。
**费用：** 免费。
### 即将来临的工具
_channel_videos` 和 `get_video_comments` 原计划在 0.3.0 中发布，但由于我们等待上游 `youtubei.js` 发布针对 YouTube 2026 响应形状更改的修复而推迟到 0.4.0。频道列表在 InnerTube 层失败，返回 HTTP 400，并且 `info.getComments()` 不再附加到解析的 `VideoInfo`。两者将在库赶上后立即返回。
## 技能
存储库附带一个 Agent 技能（一个 `SKILL.md`，您的助手按需加载），教它如何**正确**使用这些工具 — 使用免费工具预先检查候选者，优先使用作者字幕，依赖免费文字记录缓存，并使用 `[mm:ss]` 引用答案。
- [`skills/youtube-research`](skills/youtube-research/SKILL.md) — YouTube 研究工作流：搜索 → 检查元数据 → 有选择地提取 → 使用 `[mm:ss]` 引用合成。
要在 Claude Code 中使用它，请将文件夹复制到项目的 `.claude/skills/`（或 `~/.claude/skills/` 以全局使用）。兼容插件的主机可以直接从存储库中检测到它。
## 配置
| 环境变量 | 必需 | 默认值 | 备注 |
|---|---|---|---|
| `SCRIBEFY_API_KEY` | 是 | — | `sk_live_…`（生产环境）或 `sk_test_…`（Scribefy 测试模式） |
| `SCRIBEFY_API_BASE` | 否 | `https://api.scribefy.app` | 用于预发布环境（`https://api-staging.scribefy.app`）或自托管实例的覆盖 |
## 故障排除
**`SCRIBEFY_API_KEY is required`**
确保在 MCP 主机的配置文件中设置了 `env` 块，并且主机实际加载了它。某些主机默认剥离环境变量 — 请查看它们的文件。
**`Scribefy rejected the API key`**
密钥错误、密钥被吊销或您的订阅不再在 API + MCP 计划上。请在 [scribefy.app/dashboard](https://scribefy.app/dashboard) 上查看。
**`Not enough credits`**
工具在错误消息中返回剩余余额和费用。在 [scribefy.app/pricing](https://scribefy.app/pricing) 上充值。
**工具在我的 MCP 客户端中不显示**
编辑配置文件后，请完全重启客户端（不仅仅是聊天窗口）。如果有日志，请查看客户端的日志 — 大多数在那里显示 MCP stderr。服务器启动后打印 `scribefy-mcp: ready`。
## 许可证
MIT
