用途
apple-podcasts-mcp 是一个 MCP（Model Context Protocol）服务器，用于让 AI 智能体读取 Apple Podcasts Connect Reporter 中属于节目所有者的分析数据。它提供播放次数、独立听众、深度听众、关注者数量以及单集收听情况等指标。这些数据位于 Apple Podcasts Connect 和 Reporter 服务之后，不在 Apple 的公开目录 API 中。
该服务器是只读的。Reporter 本身只读取数据，因此该服务器无法更改节目、单集或账户。
主要能力
- 通过 MCP 工具提供 Apple Podcasts 所有者侧分析数据。
- 支持按日期范围查询，并限制单次工具调用的 Reporter 请求数量（硬上限 31）。
- 提供摘要、单集列表和关注者数据等工具。
- 每个指标通过别名表解析列名，并在响应中报告 resolvedColumns 和 unmappedColumns。
- 处理 Reporter 的数值错误码，将其映射为类型化错误。
- 支持可选的 APPLE_PODCASTS_ACCOUNT_ID 环境变量，用于多账户场景。
使用方式
前置条件
使用该服务器需要 Apple Podcasters Program 会员资格。Reporter 通过 vendor number 识别用户，而 vendor number 是会员注册后获得的。标准的免费 Podcasts Connect 账户没有 vendor number，其 Account → Details 页面显示的是 account UUID，这是不同的标识符，无法用于此处。会员注册需要支付年费，并要求具有税务和银行详细信息的法律实体。
如果未注册会员，则无需配置，该服务器无法提供帮助，应直接在 Podcasts Connect 的 Analytics 部分查看数据。
获取 vendor number 和访问令牌
两者均来自 Apple Podcasts 的 Reporter 侧，需要 Apple Podcasters Program 会员资格。已注册账户通过 Apple 的 Reporter 工具获取 vendor number 和访问令牌，具体记录在 Reporter User Guide 中。Reporter 的 generateToken 命令签发访问令牌；viewToken 显示当前令牌及其到期时间。
Apple 文档中有两个约束需要注意：
- 每个 Apple Account 只能有一个活动令牌。生成新令牌会立即使之前的令牌过期。如果账户上还有其他东西使用 Reporter，生成令牌会静默破坏它，且故障看起来与过期完全相同。
- 令牌管理不应自动化。Apple 声明这些命令“不适用于自动化使用，访问可能受到速率限制”，因此不要编写轮换脚本。
配置 MCP 客户端
该服务器已发布在 npm 上。配置块使用 npx，首次运行时会自动获取，无需克隆。
添加到 .mcp.json：
{
"mcpServers": {
"apple-podcasts": {
"command": "npx",
"args": ["-y", "apple-podcasts-mcp"],
"env": {
"APPLE_PODCASTS_VENDOR_NUMBER": "你的vendor number",
"APPLE_PODCASTS_ACCESS_TOKEN": "你的访问令牌"
}
}
}
}
添加到 ~/.codex/config.toml：
[mcp_servers.apple-podcasts]
command = "npx"
args = ["-y", "apple-podcasts-mcp"]
[mcp_servers.apple-podcasts.env]
APPLE_PODCASTS_VENDOR_NUMBER = "你的vendor number"
APPLE_PODCASTS_ACCESS_TOKEN = "你的访问令牌"
Claude Desktop 的 claude_desktop_config.json 使用与 Claude Code 相同的配置块。
服务器在没有凭据的情况下也能启动，以便客户端列出其工具。每次工具调用随后会失败，并提示缺少哪个变量。
APPLE_PODCASTS_ACCOUNT_ID 是可选的，大多数设置不需要它。当 Reporter 返回代码 214（“此令牌可访问多个账户；请指定账户号码”）时设置它。Reporter 不会自动选择账户，因此每次调用都会失败，直到指定账户。
验证访问
向助手提问：“Check my Apple Podcasts access.” 这会运行 apple_podcasts_check_access，证明令牌有效，并显示 vendor number 是否可被令牌读取。
令牌轮换
Apple Reporter 访问令牌在生成后 180 天过期。这是会破坏设置的问题，且会静默发生：服务器继续启动，工具继续列出，但每次调用开始失败。
当令牌过期时，工具返回错误。使用 Reporter 的 generateToken 签发新令牌。旧令牌在新令牌存在的那一刻停止工作，因此请在能同时更新配置时执行此操作。替换 APPLE_PODCASTS_ACCESS_TOKEN 并重启 MCP 客户端。
轮换是账户范围的，不是按应用程序的。Apple 允许每个 Apple Account 一个活动令牌。账户上其他与 Reporter 通信的东西会在轮换时开始失败，并报告相同的代码 123。如果多个东西需要 Reporter 访问，它们必须共享一个令牌并一起轮换。
建议设置时运行 apple_podcasts_check_access 并记录 tokenExpires 日期（如果 Apple 返回）。并非所有账户都会从 Sales.viewToken 获得到期时间；如果没有，响应会说明，应自行跟踪日期。在 170 天设置日历提醒。
适用场景
- 播客所有者希望让 AI 智能体分析其 Apple Podcasts 收听数据。
- 需要了解单集播放次数、深度听众和关注者趋势。
- 希望将 Apple Podcasts 分析与其他数据源结合进行综合分析。
限制
- 需要 Apple Podcasters Program 会员资格，免费账户无法使用。
- 只读，无法更改任何数据。
- 不查询公开目录、不获取评分评论、不涉及订阅和收入数据。
- 不提供下载次数，Apple 报告的是播放和听众，不是下载。
- 数据有 1-2 天的发布延迟，日期范围默认结束于两天前。
- 没有“获取原始报告”工具，所有工具都要求显式日期范围和行数上限。
- 实现基于 Apple 的 Reporter 文档和手工编写的测试夹具，尚未在真实 Apple 账户上验证。
- 令牌每 180 天过期，且轮换是账户范围的。
- 列名不硬编码，通过别名表解析，Apple 可能重命名列。
- Reporter 不是 REST，大多数失败在 HTTP 200 下返回数值代码，服务器检查响应体。
技术细节
Reporter 接受 HTTP POST，包含单个表单编码字段 jsonRequest，其中包含令牌和带括号命令的 JSON 文档。版本 2.2 很重要：基于令牌的认证需要 Reporter 2.2 或更高版本。成功的报告以 gzip 压缩（Content-Type: application/a-gzip）的制表符分隔文本返回，有一行标题且无引号。
当设置 APPLE_PODCASTS_ACCOUNT_ID 时，account 字段加入同一 JSON 文档。未设置时省略：Reporter 将空账户视为错误而非“无偏好”。
Apple 自己的客户端是 Java jar。该服务器直接重新实现线协议，因此依赖树中没有 JVM。
测试使用存根 fetch 并针对 src/tests/fixtures/ 中手工构建的夹具运行。没有测试接触 Apple。夹具固定了解析、聚合、日期和错误路径。
.github/workflows/publish.yml 在版本升级时使用 npm Trusted Publishing 发布。首次发布必须手动完成或使用细粒度访问令牌。
贡献
欢迎问题和拉取请求。特别有用的三件事：来自真实账户的任何反馈；来自真实账户的列名；服务器映射不当的 Reporter 代码。保持只读契约，保持新工具有界——显式范围和行数上限，无原始转储。
