AssemblyAI

AssemblyAI MCP 服务

一个用于 AssemblyAI API 的远程 MCP 服务。它为任何支持 MCP 的 Agent 提供五种工具，涵盖异步语音转文本、语音理解（翻译、说话人识别、自定义格式、分章节摘要、行动项）和防护机制（PII 脱敏、内容审核、脏话过滤），通过 Streamable HTTP 提供服务，并对每个请求进行身份验证，可通过 使用 AssemblyAI 登录（OAuth）或使用调用方自己的 AssemblyAI API 密钥进行身份验证。

适用于支持 MCP 授权的任何 MCP 客户端（Claude Code、Claude.ai、Cursor、MCP Inspector 等），或能够发送 Bearer 标头的客户端。基于 Next.js 16、mcp-handler 和官方 @modelcontextprotocol/sdk 构建；部署为 Vercel 无服务器函数。

快速开始

使用 AssemblyAI 登录： 添加服务器的 /mcp 端点，无需设置标头。客户端会打开 AssemblyAI 的登录和授权页面，服务器使用为该连接获取的 API 密钥；无需复制或粘贴任何内容。（此方式适用于 AssemblyAI 托管的部署；自托管副本需使用 API 密钥，详见身份验证。）

claude mcp add --transport http assemblyai https://<host>/mcp

使用 API 密钥： 将 MCP 客户端指向 /mcp 端点，并将 AssemblyAI API 密钥作为 Bearer 令牌。

Claude Code

claude mcp add --transport http assemblyai https://<host>/mcp \
  --header "Authorization: Bearer $ASSEMBLYAI_API_KEY"

通用远程 MCP 客户端配置

{
  "mcpServers": {
    "assemblyai": {
      "url": "https://<host>/mcp",
      "headers": { "Authorization": "Bearer <ASSEMBLYAI_API_KEY>" }
    }
  }
}

手边没有托管实例？运行 npm install && npm run dev，即可通过 http://localhost:3000/mcp 提供服务（详见本地开发）。

然后向 Agent 提示，例如 *“转录此音频文件并总结内容：https://assembly.ai/wildfires.mp3”*。

工具

工具	用途
submit_transcript(audio_url, ...)	开始对公开音频／视频 URL 进行异步转录。立即返回 { transcript_id, status }。
get_transcript(transcript_id)	获取当前状态；当 status 为 completed 时，返回完整结果。Agent 通常每隔约 3 秒轮询一次。
understand_transcript(transcript_id, speech_understanding)	对已完成的转录运行语音理解——翻译、说话人识别、自定义格式、分章节摘要、行动项——无需重新提交音频（LLM Gateway /v1/understanding）。
summarize_transcript(transcript_id, style?, custom_prompt?)	通过 LLM Gateway 对已完成的转录生成自由格式或自定义提示词摘要。style：bullets（默认）、paragraph、headline、action_items 或 custom。
delete_transcript(transcript_id)	永久删除转录及其数据。此操作不可撤销——仅在用户明确要求时执行。

典型 Agent 工作流： submit_transcript → 轮询 get_transcript 直至状态为 completed → 可选调用 understand_transcript／summarize_transcript → 在用户要求清理时调用 delete_transcript。如果事先已知需求，应在提交时直接请求语音理解功能，而不是事后再处理。

submit_transcript 参数范围

接受完整的公共异步转录参数范围，使用 API 原生名称，大致分组如下：

• 提示 — prompt（对音频的上下文描述，而非指令）、keyterms_prompt
• 语言 — language_code、language_codes、language_detection、 language_detection_options、language_confidence_threshold
• 模型 — speech_models（默认使用固定的 ["universal-3-5-pro", "universal-2"] 优先级列表）、temperature
• 说话人分离 — speaker_labels、speaker_options
• 防护措施 — redact_pii（以及 redact_pii_policies、redact_pii_sub、 redact_pii_audio、redact_pii_return_unredacted、 redact_static_entities）、filter_profanity、content_safety （以及 content_safety_confidence）、speech_threshold
• 语音理解，内联 — speech_understanding.request.{translation, speaker_identification, custom_formatting, summarization, action_items}， 在转录期间运行
• 其他 — sentiment_analysis（仅限英语）、entity_detection、 iab_categories、auto_highlights、multichannel、disfluencies、 custom_spelling、punctuate、format_text、audio_start_from、 audio_end_at、domain（Medical Mode 使用 medical-v1），以及 remove_audio_tags，还有 Webhook（webhook_url、 webhook_auth_header_name/_value）

省略的参数绝不会发送，使用 AssemblyAI 自身的默认值。参数含义请参阅 提交端点文档。

get_transcript 输出

所有内容都会以带标签的区块呈现在 content[].text 中，因为 一些 MCP 客户端只会将其提供给模型： --- text --- 和 --- utterances --- 始终存在；请求时或存在时还会包含情感、 实体、翻译（全文和逐条话语）、说话人识别、 自定义格式、分章节摘要、操作项、内容安全、主题、 重点内容、未编辑文本、已编辑音频 URL，以及处理 警告。原始字段会镜像到 structuredContent 中。

身份验证

每个请求都会携带 Bearer 令牌，令牌有两种类型。

OAuth 访问令牌（使用 AssemblyAI 登录）。 不带令牌的请求会收到 401 响应，其 WWW-Authenticate 会指出 /.well-known/oauth-protected-resource，该地址会指向 AssemblyAI 的授权服务器。客户端会在那里注册自身，通过同意页面让成员登录（scope 为 aai:api），然后发送收到的访问令牌。AssemblyAI 的 API 接受 API 密钥而非访问令牌，因此在请求到达 withMcpAuth 之前，src/oauth.ts 会将令牌兑换为该成员与此客户端的连接所对应的 API 密钥（POST /api/v2/oauth/api-key），之后请求会携带该密钥继续处理。此兑换流程也会验证发起请求的服务：部署的 Vercel OIDC 令牌会放入 X-AAI-Service-Token，而 AssemblyAI 只接受本项目自身的正式生产部署，因此，自托管副本无法兑换令牌，只能使用 API 密钥。每个访问令牌对应的密钥最多缓存五分钟，因此从控制面板撤销的连接会在几分钟内失效。令牌被拒绝时会返回 401（缺少 scope 时返回 403），并要求客户端重新登录；服务中断时则返回 503，不会要求重新登录。

AssemblyAI API 密钥（透传）。 MCP 客户端将 API 密钥作为 Authorization: Bearer <key> 发送（大多数客户端配置会自动添加 Bearer 前缀）。AssemblyAI 的 REST API 需要原始密钥，因此 withMcpAuth 会提取令牌、去掉前缀，并通过 extra.authInfo.token 将其传递给每个工具 回调。密钥不会写入磁盘，也不会在请求间共享——每个请求都使用随该请求传入的密钥运行。

配置

每项设置的默认值都指向 AssemblyAI 的生产端点，因此生产部署无需进行任何设置。若要在其他 AssemblyAI 环境中登录，则必须同时设置这四项，因为该环境的密钥只能用于其自身的 API。

变量	默认值	说明
ASSEMBLYAI_OAUTH_ISSUER	https://auth.assemblyai.com	受保护资源元数据中公布的授权服务器
ASSEMBLYAI_OAUTH_EXCHANGE_ORIGIN	https://www.assemblyai.com	将访问令牌兑换为 API 密钥的地址
ASSEMBLYAI_BASE_URL	https://api.assemblyai.com	AssemblyAI API
ASSEMBLYAI_LLM_GATEWAY_BASE_URL	https://llm-gateway.assemblyai.com	LLM Gateway

服务令牌无需设置：Vercel 会将其提供给部署（VERCEL_OIDC_TOKEN），并由 @vercel/oidc 读取。

扩展工具范围（仅限增量修改）

MCP 客户端会在运行时发现工具（list_tools）；客户端配置只存储 URL 和身份验证信息，不会保存工具架构快照。因此，新工具和新的可选参数会自动出现——无需重新配置客户端；对于需要执行连接测试的平台，也无需重新测试。为确保这一点，此处的所有变更都必须是增量式的：

1. 工具名称是永久的——只能添加工具，不能重命名或移除。
2. 新增输入始终是可选的，并且默认值必须保持当前行为不变。
3. get_transcript 的文本输出只能增加带标签的章节——现有章节（--- text ---、--- utterances ---、--- sentiment ---、--- entities ---）不得重命名或改变结构，因为仅支持文本的 MCP 客户端会读取 content[].text。（如果存在旧版 --- summary --- 章节，仍会呈现，但现在摘要由 summarize_transcript 工具生成，而不是由 get_transcript 生成。）同样的保护也适用于为 Speech Understanding 和防护措施新增的章节：--- translation:<lang> ---、--- translated_utterances ---、--- speaker_identification ---、--- custom_formatting ---、--- su_summary ---、--- action_items ---、--- content_safety ---、--- topics ---、--- highlights ---、--- unredacted_text ---、--- redacted_audio --- 和 --- warnings ---。
4. structuredContent 只能增量扩展——只能新增字段，不能移除或重命名。
5. 避免使用已弃用的 AssemblyAI 转录参数（auto_chapters、summarization、summary_model、summary_type）；改用 LLM Gateway。若 AssemblyAI 官方 MCP 工具已有对应形状，应与之保持一致。

本地开发

需要 Node 24.x。

npm install
npm test                # in-process smoke + OAuth exchange tests (no network)
npm run dev             # next dev on http://localhost:3000

MCP 端点：http://localhost:3000/mcp。OAuth 受保护资源元数据：http://localhost:3000/.well-known/oauth-protected-resource。登录需要使用 AssemblyAI 接受的部署（参见 身份验证）；在本地则使用 API 密钥。

使用 MCP Inspector 进行冒烟测试

npx @modelcontextprotocol/inspector

通过 Streamable HTTP 连接到 http://localhost:3000/mcp，并将 AssemblyAI 密钥粘贴为 Bearer 令牌。使用公开的 mp3 URL 调用 submit_transcript，然后使用返回的 id 调用 get_transcript，直到转录完成。

使用 curl 进行冒烟测试

# No auth — expect 401
curl -i -X POST http://localhost:3000/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

# With your AssemblyAI key as the Bearer token — expect 200 + Mcp-Session-Id
curl -i -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer $ASSEMBLYAI_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

实时端到端测试（实际调用 AssemblyAI，实际转录）

ASSEMBLYAI_API_KEY=... npm run test:live                       # against localhost:3001
ASSEMBLYAI_API_KEY=... MCP_URL=https://<host>/mcp npm run test:live

通过 Streamable HTTP，使用 MCP SDK 客户端驱动运行中的服务：工具发现、submit_transcript 的所有功能标志、speech_model_used 断言、summarize_transcript、内联 Speech Understanding（翻译和分章节摘要）、防护措施（内容安全）、通过 understand_transcript 执行事后 Speech Understanding、音频 URL 错误时的优雅失败，以及通过 delete_transcript 清理。每当 submit_transcript 返回转录 id 时，都会立即记录，并在 finally 块中删除，因此即使测试中途失败，测试套件也会清理所有成功创建的转录。每次运行会消耗几美分的转录额度。

针对部署进行登录测试

MCP_URL=https://<deployment>/mcp VERCEL_PROTECTION_BYPASS=<secret> npm run test:oauth

以 MCP 客户端的方式登录，从部署中发现所有信息：401 挑战、受保护资源元数据、授权服务器元数据、客户端注册，然后通过浏览器中的授权页面使用 PKCE（点击 Allow）。接着列出工具，并使用访问令牌调用一个工具，同时检查篡改后的令牌是否会被拒绝。 VERCEL_PROTECTION_BYPASS 是部署的 Protection Bypass for Automation 密钥，用于通过 Vercel Authentication 保护的预览部署。 无需 API 密钥，也不会消耗转录额度。

项目布局

assemblyai-mcp/
├── app/
│   ├── mcp/[[...path]]/route.ts             # mcp-handler entry, wrapped with withOAuthExchange + withMcpAuth
│   └── .well-known/oauth-protected-resource/route.ts
├── src/
│   ├── server.ts                            # registerTools factory
│   ├── oauth.ts                             # Sign in with AssemblyAI: access token → API key exchange
│   ├── log.ts                               # JSON logging helpers + key hashing
│   ├── tool-errors.ts                       # shared 401/404/429 error mapper
│   ├── assemblyai.ts                        # fetch wrapper (submit, get, delete, retry)
│   ├── llm-gateway.ts                       # LLM Gateway client (summarize, understand)
│   ├── transcript-sections.ts               # section renderers for tool text output
│   ├── speech-understanding-schema.ts       # shared speech_understanding zod schema
│   ├── tools/
│   │   ├── submit-transcript.ts
│   │   ├── get-transcript.ts
│   │   ├── summarize-transcript.ts
│   │   ├── understand-transcript.ts
│   │   └── delete-transcript.ts
│   ├── smoke-test.ts                        # InMemoryTransport, mocked fetch
│   ├── oauth-test.ts                        # token exchange, stubbed (npm test)
│   ├── oauth-preview-test.ts                # sign-in against a deployment (npm run test:oauth)
│   └── live-test.ts                         # real API, Streamable HTTP client
├── package.json
├── tsconfig.json
├── next.config.js
├── vercel.json
└── README.md

日志记录

将 JSON 输出到标准输出，采用与 AssemblyAI 文档 MCP 服务相同的模式。每个工具都会生成一个包含 event、tool、keyHash、latencyMs、status 的事件。值得设置告警的高信号事件：bad_audio_url、assemblyai_rejected_key、tool_error、understanding_error、delete_error。绝不记录原始 API 密钥——只记录 sha256(key).slice(0,12)——也绝不记录转录内容。

部署

部署到 Vercel（链接项目后运行一次 vercel deploy）。Vercel Firewall 提供速率限制和 DDoS 防护。根据处理程序配置，MCP 端点位于 https://<host>/mcp，maxDuration: 60。

参考：此前的 Python 实现

此前基于 Python FastMCP 的实现先于此 TypeScript 移植版，保存在此仓库的首次提交中 （git log --reverse --oneline | head -1）。它是设计（身份验证桥接、错误处理、响应格式）的事实来源；此 TypeScript 移植版将这一设计延续到更适合无服务器部署的平台上。