Fireside.fm (unofficial)

firesidefm-mcp-server

一个用于 Fireside.fm 播客托管 API 的 MCP 服务。它让 Claude Code 或 Claude Desktop 等 MCP 主机能够读取你的播客、单集和下载统计数据，创建、编辑、发布和取消发布单集，并上传单集音频、封面图片和文字稿。

这是一个非官方项目，与 Fireside 无关，也未获其认可。

要求

• Node.js 22 或更高版本
• Fireside API 密钥，可在 https://app.fireside.fm/api_tokens 创建

只读密钥可启用读取工具；读写密钥还可启用更改单集的工具。除非你希望助手创建、编辑或发布单集，否则请使用只读密钥。一个密钥适用于你的 Fireside 账户中的所有播客。你可以在 Account > API Keys 下切换密钥的只读或读写权限；之后请重启服务，因为它会在启动时选择可用工具。

配置

变量	必需	含义
FIRESIDE_API_TOKEN	是	你的 Fireside API 密钥（fire_…）。
FIRESIDE_PODCAST	否	请求未指定播客时要使用的播客令牌或 slug。
FIRESIDE_READ_ONLY	否	设为 true 时，即使使用读写密钥，也只提供读取工具。
FIRESIDE_UPLOAD_DIRS	否	允许上传文件所在的目录，分隔方式与 PATH 相同（macOS 和 Linux 使用 :，Windows 使用 ;）。必须是绝对路径；开头的 ~/ 表示你的主目录。未设置此项时将禁用上传。

启动时，服务会使用密钥向 Fireside 验证。只有密钥具有读写权限且未设置 FIRESIDE_READ_ONLY 时，才会提供写入工具。密钥被拒绝时，服务会停止运行，并在 stderr 中说明原因。如果因其他原因（例如网络错误或 Fireside 服务中断）无法验证密钥，服务会仅启用读取工具并在 stderr 中说明原因；重启服务即可重试。

只有在使用读写密钥且设置了 FIRESIDE_UPLOAD_DIRS 时，才会提供 fireside_upload_file。它只会发送这些目录中的文件（检查前会跟随符号链接，并在文件打开后再次检查；无法区分硬链接与其指向的文件；如果另一个程序恰好同时改写这些目录，也可能造成检查竞态），因此请将该变量设为存放已完成单集文件的文件夹，而不是你的主目录。

以下两个主机都会以纯文本形式将密钥存储在配置文件中。

Claude Code

claude mcp add fireside \
  --env FIRESIDE_API_TOKEN=fire_… \
  --env FIRESIDE_PODCAST=your-podcast-slug \
  -- npx -y firesidefm-mcp-server

这只会为当前项目添加服务。添加 --scope user 可使其在所有项目中都可用。

Claude Desktop

编辑 Claude Desktop 的配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

在 mcpServers 下添加一个条目（如果文件中还没有该对象，请先创建）：

{
  "mcpServers": {
    "fireside": {
      "command": "npx",
      "args": ["-y", "firesidefm-mcp-server"],
      "env": {
        "FIRESIDE_API_TOKEN": "fire_…",
        "FIRESIDE_PODCAST": "your-podcast-slug"
      }
    }
  }
}

然后退出并重新打开 Claude Desktop。

Claude Desktop 不会读取你的 shell 配置文件，因此，如果你通过 nvm 等版本管理器安装了 Node，它可能无法找到 npx。此时，请将 "command" 设为 which npx 打印出的完整路径。

工具

播客和剧集可以按令牌或 slug 指定。剧集的 slug 默认为剧集编号，因此“第 42 集”可以使用，除非你在控制面板中自定义了 slug（例如 s02e04）。

工具	需要读/写密钥	功能
fireside_get_account		已连接的账户，以及其密钥是只读还是读/写。
fireside_list_podcasts		你拥有或参与协作的播客。
fireside_get_podcast		单个播客的详情和累计下载量。
fireside_list_episodes		剧集，按时间从新到旧排列，包括草稿和已安排的剧集；可按状态筛选。
fireside_get_episode		单个剧集的所有字段，包括节目简介。
fireside_get_episode_metrics		每集在 1、7、14、30 和 90 天内的下载量、Spotify 下载量及总量。
fireside_get_monthly_downloads		每个日历月的下载量和累计总量。
fireside_get_daily_downloads		播客或单集每天的下载量，Spotify 单独统计；每次调用最多查询一年。
fireside_create_episode	✓	创建私密草稿剧集，可选择添加音频、封面图和文字稿。
fireside_update_episode	✓	更改标题、副标题、slug、节目简介、季数、类型、露骨内容标记、音频、封面图或文字稿。
fireside_upload_file	✓	从 FIRESIDE_UPLOAD_DIRS 上传 MP3、封面图片（JPG、PNG、GIF 或 WebP）或纯文本文字稿，并将其附加到剧集，或返回 file_url 供创建和更新时使用。
fireside_publish_episode	✓	立即发布、安排发布或回填发布日期；可设为公开或不公开列出。
fireside_unpublish_episode	✓	将剧集恢复为私密草稿。

fireside_get_episode 会返回剧集的预览链接。任何拥有该链接的人都可以播放剧集，即使剧集尚未发布。

上传 MP3 前，服务会读取其标头。不包含 MP3 音频的文件（例如改了扩展名的 WAV）会被拒绝。如果文件规格与 Fireside 控制面板建议的 MP3 设置（单声道、64–96 kb/s、44.1 kHz）不符，服务会列出差异并中止上传；助手应先询问你，只有在设置 accept_audio_specs: true 时才会按原样上传。音频大小限制取决于你的 Fireside 方案，API 不会报告该限制；Fireside 会在发送任何内容前检查文件大小，随后服务会将文件大小列为可能原因。

上传的音频会在后台传输到剧集；剧集上的 audio_status 会先显示 processing，然后变为 ready 或 failed（并显示 audio_error）。封面图和文字稿会在调用过程中附加。大型音频文件的上传时间可能超过 MCP 主机允许的工具调用时长；在 Claude Code 中，可通过 MCP_TOOL_TIMEOUT 环境变量（毫秒）提高限制。

限制

以下限制来自 Fireside API 本身：

• 无法通过 API 上传章节。发布没有音频的剧集会失败。
• 文件必须符合方案限制：封面图最大为 1.91 MB，文字稿最大为 195 KB，音频不得超过方案的 MP3 限制。
• 无法删除剧集，也无法更改播客设置。
• 如果控制面板中为剧集启用了相关设置，发布时也会将内容发布到播客已连接的社交账户。API 无法查看或更改此设置。
• 每次请求最多返回 90 天的每日下载量。服务会合并请求，因此一次调用最多可涵盖一年；更长时间段请分批查询。
• 每个密钥每分钟最多可发出 120 次请求。遇到短暂的速率限制时，服务会等待限制解除；遇到较长限制时则会报告。

开发

npm install
npm run build       # compiles to dist/
npm run typecheck
npm test            # unit and in-process MCP tests; no network
npm run test:e2e    # builds, then runs dist/cli.js over stdio against a local stand-in API
npm run check       # all of the above
npm run dev         # run from source with tsx

scripts/ 中有两项检查，会使用从 macOS 钥匙串读取的密钥连接真实的 Fireside API 运行；请参阅每个文件顶部的注释。live-read-check.ts 只读取数据。live-draft-check.ts 会创建并编辑一个草稿剧集，你之后需要在控制面板中将其删除；此检查不会发送发布或取消发布请求。

许可证

MIT