OP3 MCP Server

---

一个适用于 OP3（开放播客前缀项目）的 MCP 服务。它为 AI 助手提供了大多数托管平台 API 不会公开的播客分析数据：随时间变化的下载量、听众地域、听众使用的应用，以及单集明细。

从设计上就是只读的。 OP3 是一项分析服务。此服务只读取数据，无法进行任何更改，因此可以放心交给 Agent 使用。

创建此项目的原因。 大多数播客托管平台几乎不会通过 API 公开数据。例如，Transistor 的 API 只返回下载量，其他信息很少：没有地域数据、应用占比或单集近期表现趋势。OP3 拥有这些数据，因为它会在重定向时记录每次下载。此服务让 Agent 可以访问这些数据。

什么是 OP3？

OP3 是一款免费、开放的播客分析前缀。只需在媒体文件 URL 前加上 https://op3.dev/e/，OP3 就会在重定向到真实音频文件前记录每次下载。随后，它会提供下载量、地域和应用占比数据。统计页面公开可见；API 则需要令牌。详情请参阅 https://op3.dev。

如果你的订阅源尚未使用 OP3 前缀，OP3 就没有相关数据。请参阅下文“添加 OP3 前缀”。

工具

工具	返回内容	OP3 端点
op3_get_show	节目 UUID、标题、播客 GUID、统计页面 URL、可选的单集列表	GET /shows/{showUuidOrPodcastGuidOrFeedUrlBase64}
op3_show_downloads	月度下载量、每周明细、每周平均值	GET /queries/show-download-counts
op3_episode_downloads	单集在 1/3/7/30 天内及累计的下载量	GET /queries/episode-download-counts
op3_top_apps	过去 3 个日历月中，下载占比最高的应用/播放器	GET /queries/top-apps-for-show
op3_top_countries	听众人数最多的国家或地区（根据原始记录计算）	GET /downloads/show/{showUuid}
op3_downloads_timeseries	日期范围内的原始下载事件（时间、国家、应用、设备）	GET /downloads/show/{showUuid}

大多数工具都需要节目 UUID。先使用 op3_get_show，将订阅源 URL 或播客 GUID 转换为 UUID。

所有列表工具都接受 limit 参数，默认值较小（10），以控制响应大小。Agent 按响应消耗令牌。

设置

1. 获取令牌

1. 前往 https://op3.dev 并登录。
2. 打开 API 令牌页面并复制令牌。
3. 若要试用，OP3 还提供了一个共享预览令牌 preview07ce，可用于查询公开节目。

2. 查找节目 UUID

如果你知道订阅源 URL 或播客 GUID，请让助手使用它运行 op3_get_show，即可获取 UUID。你也可以从节目 OP3 统计页面的 URL 中读取 UUID：https://op3.dev/show/{showUuid}。

3. 配置 MCP 客户端

Claude Code

添加到你的 .mcp.json：

{
  "mcpServers": {
    "op3": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/op3-mcp"],
      "env": {
        "OP3_API_TOKEN": "your-op3-token"
      }
    }
  }
}

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "op3": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/op3-mcp"],
      "env": {
        "OP3_API_TOKEN": "your-op3-token"
      }
    }
  }
}

4. 验证

向你的助手询问：“用我的订阅源 URL 查找我在 OP3 上的节目”，然后询问“上个月获得了多少次下载？”

添加 OP3 前缀（如果你还没有使用 OP3）

只有当下载通过 OP3 前缀时，OP3 才会有数据。开始使用：

1. 在你的播客托管平台中，在单集音频 URL 前添加 https://op3.dev/e/。许多托管平台（Transistor、Buzzsprout 等）都提供一键启用 OP3 的开关。查看托管平台的设置，寻找“OP3”或“analytics prefix”选项。
2. 新的下载将开始被记录。添加前缀之前的历史下载不会补录。
3. 在 https://op3.dev 上找到你的节目，并记下其统计页面 URL，其中包含你的节目 UUID。

限制

请阅读以下内容，了解这些数字的含义。

• 地理数据是计算得出的样本，并非精确总数。 OP3 没有按国家/地区汇总的接口。op3_top_countries 会获取原始下载记录，并在客户端侧按国家/地区计数。结果具有代表性，但不是精确的累计数据。OP3 按时间从早到晚返回原始记录，因此如果你没有传入明确的 start，工具默认使用最近 90 天（window_days）；否则样本会包含该节目的最早下载，而不是近期听众。在时间窗口内，记录仍按时间从早到晚采样，因此对于下载量较大的节目，max_records 样本会偏向窗口开始时的数据；响应中包含 sampleHitCap，可据此判断窗口内的记录是否多于采样数。增大 max_records（上限为 20000）可获得更大、更具代表性的样本，但会牺牲速度和速率限制余量。
• 没有设备细分工具。 OP3 的原始记录包含 deviceType 和 deviceName，但没有设备汇总查询。你可以通过 op3_downloads_timeseries 查看每条记录的设备信息。应用占比数据可通过 op3_top_apps 获取。
• 热门应用仅涵盖最近三个日历月。 该时间窗口由 OP3 固定，无法配置。
• 数据从添加前缀时开始。 OP3 无法报告未经过其重定向的下载。
• OP3 的下载查询默认排除机器人，这通常正合你意。
• 速率限制尚未公开说明。 请将 limit 和 max_records 设为适中的值。服务器会在 HTTP 429 时返回明确的错误。

类型化错误

API 故障会映射到类型化错误层次结构（src/errors.ts 中以 OP3APIError 为基类，并根据 HTTP 状态码使用 AuthError、RateLimitError、NotFoundError、ValidationError 和 ServerError 子类）：

• AuthError（401/403）——OP3 令牌缺失或无效。
• RateLimitError（429）——对 OP3 API 的请求过多。
• NotFoundError（404）——节目、订阅源或资源不存在（或尚未加入 OP3）。
• ValidationError（400）——请求参数格式错误或无效。
• ServerError（5xx）——OP3 端发生故障；消息中会保留具体状态码（500、502、503 等）。
• OP3APIError——基类，用作未映射状态码或网络故障的回退错误。

每次工具调用在失败时仍会返回相同的 isError: true 响应结构；类型化层次结构只是让错误消息具体说明故障原因，而不是统一返回“API error”这一通用字符串。

开发

git clone https://github.com/conorbronsdon/op3-mcp.git
cd op3-mcp
npm install
npm run build
npm test

本地运行：

OP3_API_TOKEN=your-token npm start

测试会模拟 fetch，不会发起网络请求。

贡献

欢迎提交问题和拉取请求。如果 OP3 端点的返回结构发生变化，或者有值得封装为工具的汇总查询，请提交问题，说明你的需求以及对应的 OP3 端点。请遵守只读约定：此服务用于报告分析数据，不会更改任何内容。

关于

由 Conor Bronsdon 开发并维护。我主持 Chain of Thought 播客，内容涵盖 AI 基础设施、开发者工具，以及从业者实际如何使用这些工具。我开发这个项目，是为了将真实的听众数据分析结果融入运营该节目的 Agent 工作流。

配套工具：

• podcast-benchmark：根据公开信号将你的节目与同类节目进行基准比较。它是本文所述私有 OP3 数据分析的公开数据补充。
• Transistor MCP：Transistor.fm 官方 MCP 服务。提供单集、发布和数据分析功能。
• substack-mcp：在 Substack 上阅读文章和管理草稿，适用于 Agent 工作流。
• podcastindex-mcp：Podcast Index MCP 服务，可按人物或主题搜索、查看热门节目和订阅源健康状况。
• ai-tools-for-creators：为以创意为生的人精选的 AI 技能和 MCP 服务列表。

更多信息请访问 chainofthought.show，或在 X 上关注。

---

免责声明

这是一个独立的个人项目，与任何公司均无关联，也未获得任何公司的赞助或认可。文中表达的所有观点均为我个人观点。

许可证

MIT