# MCP服务器接入指南

> 在Claude、ChatGPT、VS Code等客户端接入transcript1，直接让AI助手转录音视频。附Cursor MCP和Claude Code MCP配置。

Canonical: https://transcript1.com/zh/docs/mcp
Language: zh-Hans
Last updated: 2026-10-15

将transcript1的远程[Model Context Protocol](https://modelcontextprotocol.io/)服务器接入AI助手，助手就能转录并读取音视频内容。可以提交YouTube、X、TikTok、Instagram、Facebook、Bluesky链接，也可以处理上传的音视频文件。其他支持的公开录制内容和使用限制，见[来源与选项](https://transcript1.com/zh/docs/sources-and-options)。

帖子必须公开；有多个视频时，只转录第1个。YouTube、X、TikTok、Bluesky、Dailymotion和LinkedIn都支持使用视频原语言的可用字幕。auto模式下，没有可用字幕就改用AI语音转文字，每分钟价格不变。除YouTube外，平台字幕只有分段时间戳（`words: null`），自动生成的字幕也没有逐词时间戳。选择`captions`（仅字幕）时，不会下载或转录音频；开启说话人分离或设置`source=stt`时，则跳过字幕，直接转录音频。详细规则见[来源与选项](https://transcript1.com/zh/docs/sources-and-options)。

- **服务器地址**：`https://api.transcript1.com/mcp`，使用streamable HTTP。
- **认证方式**：Claude和ChatGPT通过OAuth 2.1授权，连接时登录transcript1并批准访问即可。Cursor、VS Code、Claude Code和AI智能体使用API密钥，通过`Authorization: Bearer t1_...`发送。密钥在[“API keys”](https://transcript1.com/dashboard/account/tokens)页面创建。

MCP工具会用当前凭据调用`/v1`[REST API](https://transcript1.com/zh/docs/api-reference)，参数校验、扣费规则和错误码都与REST API一致。MCP与其他请求共用账号的分钟余额和请求额度。

## 可用工具

| 工具 | 用法 |
|---|---|
| `transcribe` | 提交受支持的视频链接，必填`url`，可选`platform`、`source`、`language`、`diarize`、`format`和`wait_seconds`。平台会根据链接自动识别。工具等待转录后返回文本的第1页；还没完成时返回`id`，供后续查询。 |
| `get_transcription` | 用`id`查询任务状态或读取转录文本。可传入`wait_seconds`、`format`、`from_seconds`和`max_chars`。 |
| `list_transcriptions` | 按从新到旧的顺序列出最近任务，不附转录文本。可传入`status`、`platform`、`limit`和`cursor`。 |
| `create_upload` | 为本地文件创建分块上传。必填`filename`、`size`和`request_id`，其中`request_id`由调用方生成，格式为UUID。可选`mime_type`、`language`和`diarize`。 |
| `get_upload_status` | 查询服务端已收到哪些分块，方便继续上传。 |
| `complete_upload` | 检查分块是否完整，并将转录任务加入队列。 |
| `delete_transcription` | 任务仍在运行时，取消任务并退还分钟数；任务已结束时，删除任务及转录文本。 |
| `get_account` | 查询分钟余额、当前套餐和续费日期。 |

### 默认设置与分页

- `format`默认是`text`，每段文本占1行，行首带时间戳。识别出说话人时，还会附上说话人标签，例如`[00:01:02] Speaker 1: Good morning.`。也支持`srt`、`vtt`和`json`。
- `wait_seconds`默认50秒，可设为0到55。等待结束时若仍未完成，工具会说明任务还在运行，并返回`id`。把id传给`get_transcription`，就能继续等待。
- 长文本按页返回。`max_chars`默认60,000，可设为1,000到100,000。每页在分段结束处截断，并返回`next_from_seconds`。读取下一页时，将该值传给`from_seconds`。
- 返回的`transcript_source`说明文本来自哪里，可为`youtube_captions`、`x_captions`、`tiktok_captions`、`bluesky_captions`、`dailymotion_captions`、`linkedin_captions`或`speech_to_text`。`caption_kind: null`表示无法确定字幕轨道的来源，不能据此认定是创作者上传的字幕。

### 不要重复提交已有任务

`transcribe`总会启用`reuse_recent`。使用完整视频链接时，如果同一视频在24小时内已经用相同选项转录过，就会返回之前的转录，不再扣费。短链接不支持这种复用。工具会注明是否复用了已有转录。需要确认进度时，优先调用`get_transcription`或`list_transcriptions`，不要重新提交视频。

### 本地文件如何上传

MCP本身不传文件内容。先用`create_upload`取得转录`id`、分块URL模板、`X-Upload-Token`和分块列表，再让AI助手在MCP之外通过HTTP `PUT`逐块上传，最后调用`complete_upload`。工具也会返回控制台上传页的链接，无法直接发送文件时可改用该页面。上传协议见[文件上传](https://transcript1.com/zh/docs/uploads)。

### 需要Webhook时使用REST API

MCP工具不提供Webhook参数。需要转录完成通知时，请通过REST API配置[Webhook](https://transcript1.com/zh/docs/webhooks)。

## Claude

在Claude中，通过自定义连接器接入远程MCP服务器：

1. 进入Claude的连接器设置，新增自定义连接器。
2. 将名称设为`transcript1`，服务器URL设为`https://api.transcript1.com/mcp`。
3. 按提示登录transcript1并授权。连接器会申请`transcriptions:read`和`transcriptions:write`权限。

连接后即可让Claude转录视频，例如“转录https://www.youtube.com/watch?v=dQw4w9WgXcQ”。是否能使用自定义连接器，取决于Claude套餐。

## ChatGPT

ChatGPT也使用自定义连接器：

1. 进入ChatGPT的连接器设置，新增MCP服务器的自定义连接器。
2. 服务器URL填入`https://api.transcript1.com/mcp`。
3. 完成transcript1登录并授权访问。

自定义连接器是否可用，取决于ChatGPT套餐和工作区设置；有些配置需要先开启开发者模式。

## 在Cursor中配置MCP

点击链接即可安装：[添加transcript1到Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=transcript1&config=eyJ1cmwiOiJodHRwczovL2FwaS50cmFuc2NyaXB0MS5jb20vbWNwIn0=)

也可以手动编辑`.cursor/mcp.json`，添加以下配置，并在`Authorization`请求头中填入API密钥：

```json
{
  "mcpServers": {
    "transcript1": {
      "url": "https://api.transcript1.com/mcp",
      "headers": {
        "Authorization": "Bearer t1_YOURKEY"
      }
    }
  }
}
```

## VS Code

点击链接即可安装：[添加transcript1到VS Code](vscode:mcp/install?%7B%22name%22%3A%22transcript1%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.transcript1.com%2Fmcp%22%7D)

手动配置时，将以下内容加入工作区的`.vscode/mcp.json`：

```json
{
  "servers": {
    "transcript1": {
      "type": "http",
      "url": "https://api.transcript1.com/mcp",
      "headers": {
        "Authorization": "Bearer t1_YOURKEY"
      }
    }
  }
}
```

## 在Claude Code中配置MCP

先将`t1_YOURKEY`换成自己的API密钥，再执行：

```bash
claude mcp add --transport http transcript1 https://api.transcript1.com/mcp --header "Authorization: Bearer t1_YOURKEY"
```

## 接入其他客户端

只要客户端支持远程MCP服务器，就可以连接`https://api.transcript1.com/mcp`，并通过请求头`Authorization: Bearer t1_...`提供密钥。

## 用命令接入Claude Desktop等客户端

如果客户端要求用命令启动MCP服务器，可使用`npx -y @transcript1/mcp`，并通过`TRANSCRIPT1_API_KEY`提供API密钥。这个包负责连接托管的transcript1服务器，需要Node.js 18或更高版本。

Claude Desktop的配置文件为`claude_desktop_config.json`。加入以下内容，并将`t1_YOURKEY`换成在[“API keys”](https://transcript1.com/dashboard/account/tokens)页面创建的密钥：

```json
{
  "mcpServers": {
    "transcript1": {
      "command": "npx",
      "args": ["-y", "@transcript1/mcp"],
      "env": { "TRANSCRIPT1_API_KEY": "t1_YOURKEY" }
    }
  }
}
```

## Agent Skill

Agent Skill通过简短的`SKILL.md`指令文件，告诉AI智能体如何调用transcript1。智能体支持Skill时，可从[https://transcript1.com/.well-known/agent-skills/transcript1/SKILL.md](https://transcript1.com/.well-known/agent-skills/transcript1/SKILL.md)添加。

支持自动发现Skill的智能体，也能从`https://transcript1.com/.well-known/agent-skills/index.json`索引找到该文件。

## 工具报错后怎么处理

调用失败时，工具会返回错误码、错误说明和AI助手可执行的后续操作，格式为`<code>: <message>. <next step>`。其中`code`与REST API一致。分钟数不足时，例如：

```text
insufficient_minutes: 20 minutes needed, 3 remaining. Top up at https://transcript1.com/dashboard/billing
```

所有错误码和处理方法见[错误说明](https://transcript1.com/zh/docs/errors)。转录任务失败时也使用同样的格式，并附上失败码，例如`media_private`或`no_captions`。