Audivo

Audivo MCP 服务

为 Claude、ChatGPT、Codex、Cursor 和任何其他 MCP 客户端提供播客文字稿，由 Audivo API 提供支持。 询问某一集，即可获取文字稿。

转录 Acquired 的最新一集并总结内容。

有两种连接方式。托管端点提供 11 个工具。本地服务也提供相同的 11 个工具，其中 transcribe 还可处理你机器上的文件或 YouTube 链接，另外还提供 upload_audio 和 youtube_search。两者都会向可渲染 MCP Apps 的客户端提供一个应用。

	托管	本地
运行位置	Audivo 的服务	由客户端启动，在你的机器上运行
传输方式	https://api.audivo.dev/mcp 上的 Streamable HTTP	通过 npx -y @audivo/mcp@latest 使用 stdio
凭据	使用 OAuth 登录，或提供 Authorization: Bearer hk_live_…	AUDIVO_API_KEY 环境变量
适用于	网页版和桌面版 Claude、ChatGPT，以及任何接受 URL 的客户端	Claude Code、Codex、Cursor、VS Code，以及所有会启动进程的客户端
YouTube	否	是，通过 yt-dlp 在你的机器上下载

工具

工具	功能	消耗额度
transcribe	默认工具。 输入一集节目，分页获取其文字稿	是，每分钟音频约消耗 1 点额度
search_shows	按名称、主持人或主题查找节目	否
chart_shows	查看某个类别的当前排行榜	否
list_episodes	查看某个节目的分集列表，按最新优先	否
quote	在执行任何操作之前，为多个剧集的选择估算价格	否
confirm	将报价转为任务组	是，最多不超过报价上限
group_status	查看组内任务的状态，以及哪些文字稿已就绪	否
list_groups	查看你最近的任务组	否
cancel_group	停止尚未开始的任务并返还相应额度	否
read_transcript	分页读取任务的文字稿；任务运行中时会等待	否
list_transcripts	查看你最近的文字稿及其标题	否
upload_audio	声明并上传这台机器上的文件	否（仅本地）
youtube_search	当某集没有播客订阅源时，在 YouTube 上查找该集	否（仅本地）

transcribe

传入一个单集：Apple Podcasts 链接、带 guid 的 feed_url、来自 list_episodes 的 episode_id（同时提供该节目的 feed_url 和 itunes_id，这样就能找到尚未有人转录的单集），或 upload_id；在本地服务上，还可以传入 YouTube 链接或绝对 path。

• 已转录的单集会立即返回。
• 新单集会成为一个任务。transcribe 会在调用期间等待任务完成：托管服务上最多等待 20 秒（其网关允许等待 29 秒）；本地服务默认最多等待 50 秒，并会向请求进度的客户端报告进度。如果任务仍在运行，返回结果会包含 job_id，而 read_transcript 会继续等待。
• 转录文本每次按页返回，每页约 40,000 个字符（大约 50 分钟的语音）。每页都会给出下一页所需的确切调用。
• 如果调用可能超出 max_credits，它会在花费任何额度前拒绝调用。任务会预留其费用上限（估算费用加 25%），并按实际测量的音频时长结算，绝不会超过上限。
• 相同调用重复执行会返回同一个任务，不会再次扣费：幂等键由请求生成。

如需一次处理多个单集——例如排行榜或全部旧节目——请使用 quote，然后使用 confirm；如果模型没有复述报价总额，调用就会被拒绝。

应用

能够呈现 MCP Apps 的客户端——ChatGPT、Claude 等——会在 Audivo 自带的视图中展示结果，而不只是显示文本：

• transcribe 会打开转录阅读器：显示节目和单集、时长、语言和费用，然后显示带时间戳的转录文本、搜索框，以及按需加载更多页面的功能。仍在运行的任务会显示进度，并在完成后填入结果。
• list_transcripts 会打开你的资料库：显示可在阅读器中打开的近期转录文本，还提供搜索功能，可查找节目、列出单集，并在你确认预估费用后转录其中一个单集。 ChatGPT 还会将资料库放在侧边栏中，并作为对话旁边的一个标签页。

该应用是一个独立页面，以 ui://audivo/app-v1.html 提供服务。它不会从任何域加载内容，因此无需声明任何域。其数据通过每个结果中的 _meta 传递，由宿主提供给应用，不会提供给模型；模型仍会像以前一样收到相同的围栏文本。所有标题和转录文本行都作为文本呈现，绝不会作为标记语言处理。不支持 MCP Apps 的客户端会忽略这些内容。

应用源代码位于 ui/；npm run build:ui 会将其打包到 src/app-html.ts，如果两者不一致，测试就会失败。

本地：使用 npx 运行

你需要从 Audivo 控制面板获取 API 密钥。密钥只会显示一次。在客户端启动服务时使用的环境中设置密钥，然后添加服务。

Claude Code（或者安装 Audivo 插件，它会同时添加此服务和技能）

claude mcp add --scope user audivo -e AUDIVO_API_KEY=hk_live_... -- npx -y @audivo/mcp@latest

Codex

codex mcp add audivo --env AUDIVO_API_KEY=hk_live_... -- npx -y @audivo/mcp@latest

Cursor、Claude Desktop、Windsurf 和其他使用 JSON 配置的客户端

{
  "mcpServers": {
    "audivo": {
      "command": "npx",
      "args": ["-y", "@audivo/mcp@latest"],
      "env": { "AUDIVO_API_KEY": "hk_live_..." }
    }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "audivo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@audivo/mcp@latest"],
      "env": { "AUDIVO_API_KEY": "hk_live_..." }
    }
  }
}

请勿将包含真实密钥的文件提交到 Git 或分享至聊天中。

更新

@latest 会让 npx 在客户端每次启动服务时都从 npm 查找此软件包，因此新版本会在你的下次会话中生效。如需在当前会话中应用更新，请重启服务：在 Claude Code 中输入 /mcp，选择 audivo，然后选择 Reconnect。不带 @latest 的规格也能正常使用，但如果当前项目中存在副本，不带版本标记的 @audivo/mcp 会优先解析到该副本。Audivo 会持续更新托管服务 https://api.audivo.dev/mcp。

环境

变量	必填	含义
AUDIVO_API_KEY	是	你的 API 密钥。前面带有 Bearer 也可以，系统会将其规范化。
AUDIVO_API_BASE_URL	否	API 源站。默认为 https://api.audivo.dev。必须是公开的 https 源站：不能包含用户信息，也不能是环回或私有地址。
AUDIVO_YTDLP_PATH	否	用于 YouTube 的 yt-dlp 二进制文件，不使用 PATH 中的版本或托管副本。
AUDIVO_CACHE_DIR	否	托管版 yt-dlp 的存放位置。默认为用户缓存目录（~/Library/Caches/audivo-mcp、~/.cache/audivo-mcp 等）。

服务除了协议消息外，不会向 stdout 写入任何内容。日志行以 JSON 格式写入 stderr，且不会包含密钥。

YouTube（仅限本地服务）

当节目没有公开的 RSS 源时（许多节目只在 YouTube 上发布），search_shows 将找不到结果。 在本地服务上，youtube_search 可以找到节目，transcribe 则会处理其链接：

在 YouTube 上查找 Acquired 的 Costco 节目并转录

transcribe 会通过 yt-dlp 在你的计算机上下载视频的音频，仅下载音频且不进行转码；随后将其作为你自己的上传文件上传到 Audivo，并进行转录。转录文本仅对你的账户可见。

查找 yt-dlp 的顺序如下：AUDIVO_YTDLP_PATH；PATH 中的 yt-dlp；否则，从项目的 GitHub 官方发布页面下载适用于你平台的独立二进制文件，并将其保存到用户缓存目录。启用该文件前，会根据该版本的 SHA2-256SUMS 校验文件。此软件包没有安装脚本：首次调用 YouTube 功能前不会下载任何内容。托管副本停止工作时，系统会将其更新到最新版本并重试调用；你自行安装的 yt-dlp 则不会被触碰。yt-dlp 会将运行此服务的 Node 作为其 JavaScript 运行时。

下载由你在自己的计算机上使用自己的账户执行；与任何上传一样，你有责任确保自己有权转录所下载的内容。Audivo 的服务器不会从 YouTube 获取内容，因此托管服务不提供这些功能。

上传自己的音频

你录制的录音、访谈，或已保存在磁盘上的任何文件：

转录 /Users/alex/Downloads/interview.m4a

使用 path 调用 transcribe 时，会先向 Audivo 提交文件信息（哈希值、大小、内容类型和时长），再使用提交信息返回的签名 URL 将文件字节直接上传到 Audivo 的存储空间，并进行转录。upload_audio 只执行前两个步骤，并返回一个 upload_id，方便你将多个上传文件一起引用。path 必须是绝对路径。

限制：文件大小为 1 字节至 5 GiB，时长最长为 10 小时，且内容类型必须是以下之一：audio/mpeg、audio/mp3、audio/mp4、audio/m4a、audio/x-m4a、audio/aac、audio/x-aac、audio/ogg、audio/opus、audio/flac、audio/x-flac、audio/wav、audio/x-wav、audio/webm。上传文件会保留 7 天，其转录文本仅对你的账户可见；每个账户最多可同时保存 100 个未过期上传文件，总大小不超过 10 GiB。请参阅上传指南。

托管服务：让客户端连接到该 URL

设置	值
MCP URL	https://api.audivo.dev/mcp
传输方式	Streamable HTTP
身份验证	OAuth（登录 Audivo），或 Authorization: Bearer hk_live_...

支持 MCP 授权的客户端——Claude、ChatGPT、Claude Code、VS Code——只需提供 URL： 它们会打开 Audivo 登录页面，你批准连接后，它就会显示在仪表盘的已连接应用下， 并且你可以撤销连接。例如，在 Claude Code 中：

claude mcp add --transport http --scope user audivo https://api.audivo.dev/mcp

对于需要固定请求头的客户端，或用于自动化的场景，请发送 API 密钥：

claude mcp add --transport http --scope user audivo https://api.audivo.dev/mcp \
  --header "Authorization: Bearer hk_live_..."

各客户端的说明见连接指南。托管服务就是此软件包的 lambda 导出项，由 Audivo 部署。

工作原理

• 无状态。 每次工具调用都会使用调用者自己的凭据，在公共 API 上执行一次或几次带类型的调用。服务不会保留任何表、缓存，也不会在调用进行期间之外保存凭据副本。
• 设有隔离栏。 节目名称、剧集和视频标题、描述以及转录文本均由发布者撰写。每项内容都会放入标记为不可信内容的隔离栏中，并附带每个响应专属的随机数后再传给模型，以防播客将指令偷偷带入会话。
• 设有上限。 transcribe 的开支不会超过任务上限和调用者的 max_credits；confirm 会比较模型给出的总额与报价所包含的总额，如果不一致，则拒绝发送任何内容。API 也会在其端执行这两项检查。
• 由契约定义类型。 src/contract/types.ts 根据已发布的 OpenAPI 规范 contract/openapi.yaml 生成；如果两者不一致，测试会导致构建失败。
• 仅在本地运行。 upload_audio、youtube_search 以及 transcribe 的文件和 YouTube 输入都在你的机器上运行；托管服务永远不会看到你的文件，也不会从第三方网站获取内容。

开发

npm ci
npm test            # vitest
npm run typecheck
npm run lint
npm run build       # dist/

如需应用规范变更：npm run contract:sync 会获取已发布的规范并重新生成类型。使用密钥在本地运行：

AUDIVO_API_KEY=hk_live_... node dist/bin.js

在 MCP 客户端中实时重新加载

npm run dev:server 会通过一个小型代理运行 src/，使用 tsx 在每次保存时重启服务，将客户端握手重新发送到新进程，并发送 tools/list_changed。连接的客户端会使用你最新的代码，无需构建或重新连接。如果保存的内容导致启动失败，调用会收到错误，详情会写入客户端的 MCP 日志；下次保存后即可恢复。保存时仍在运行的调用会重新发送给新代码，但上传音频的调用除外（文件或 YouTube transcribe，或 upload_audio）：如果发送两次，可能会转录并收费两次，因此会先在旧代码上完成。

如需仅在此代码仓库中将其用于 Claude Code，并使其优先于用户级的 audivo 服务：

claude mcp add audivo -s local -e AUDIVO_API_KEY=hk_live_... \
  -- "$PWD/node_modules/.bin/tsx" "$PWD/scripts/dev-server.ts"

绝对路径形式的 tsx 可让客户端从任意目录启动它。在此代码仓库中，直接使用 npx -y @audivo/mcp 行不通——npm 会将此检出目录视为软件包，并且找不到已链接的 audivo-mcp 可执行文件——这也是上面的配置使用 @latest 的原因之一。

发布

更新 package.json 中的 version、server.json 中的两个版本字段，以及 src/server.ts 中的 SERVER_INFO（这些值一致之前，测试会失败）；在 CHANGELOG.md 中添加条目，提交，然后创建 v<version> 标签并推送该标签。发布工作流会将软件包连同来源证明一起发布到 npm，并以 io.github.AudivoDotDev/mcp 的名称将发布版本登记到 MCP Registry。

许可证

MIT