Podfetcher Tools
Podfetcher Tools is a Node.js client bundle for the Podfetcher API. It gives you three ways to work with podcast data from the same package:
- - a CLI for quick terminal workflows
- an SDK for custom scripts and apps
- an MCP server so agents can search shows, list episodes, and fetch transcripts
Use it when you want to discover podcasts, inspect episode catalogs, or retrieve transcripts from podfetcher.com.
Requirements
- - Node.js 20+
- INLINECODE0 set to a valid Podfetcher API key
The default API base URL is https://api.podfetcher.com. Override it only when targeting a non-production environment.
Getting Started
- 1. Create or sign in to your account at podfetcher.com.
- Generate an API key from the Podfetcher dashboard.
- Export the key before running the CLI or MCP server:
CODEBLOCK0
Optional overrides:
- -
PODFETCHER_BASE_URL for non-production environments - INLINECODE3 if you need a non-default header name
Entry Points
If the package is installed globally from npm, use these binaries:
If you are working from a local checkout instead, run commands from this directory or reference these files by absolute path from another workspace:
- - CLI: INLINECODE6
- MCP server: INLINECODE7
- SDK import: INLINECODE8
CLI Commands
Search shows
CODEBLOCK1
- -
--q is required - Returns
items[] with showId, title, and INLINECODE13 - If present, pass
nextCursor into --cursor for the next page
List episodes
CODEBLOCK2
- -
--show-id is required - Returns
items[] with episodeId, publishedAt, title, and INLINECODE21
Fetch transcript
CODEBLOCK3
- -
--episode-id is required - Without
--wait, the API may return a queued job with jobId and INLINECODE25 - With
--wait, the client polls until the transcript is ready or the timeout expires
Global CLI Options
- -
--api-key <key> or PODFETCHER_API_KEY for Podfetcher authentication - INLINECODE29 or
PODFETCHER_BASE_URL for API endpoint override - INLINECODE31 or
PODFETCHER_API_KEY_HEADER for header override - INLINECODE33
- INLINECODE34
Typical Workflow
CODEBLOCK4
MCP Server
Start the MCP server over stdio:
CODEBLOCK5
Available tools:
- - INLINECODE35
- INLINECODE36
- INLINECODE37
Example config:
CODEBLOCK6
Error Handling
- - HTTP errors are formatted as INLINECODE38
- Missing API key errors are reported before the request is sent
- Exit code is
1 on error and 0 on success
Podfetcher 工具
Podfetcher 工具是 Podfetcher API 的 Node.js 客户端包。它为您提供了三种从同一包中处理播客数据的方式：
- - 用于快速终端工作流的 CLI
- 用于自定义脚本和应用的 SDK
- 用于代理搜索节目、列出剧集和获取文字记录的 MCP 服务器
当您想要发现播客、查看剧集目录或从 podfetcher.com 获取文字记录时，可以使用它。
系统要求
- - Node.js 20+
- PODFETCHERAPIKEY 设置为有效的 Podfetcher API 密钥
默认 API 基础 URL 为 https://api.podfetcher.com。仅在针对非生产环境时覆盖它。
快速开始
- 1. 在 podfetcher.com 创建或登录您的账户。
- 从 Podfetcher 控制面板生成 API 密钥。
- 在运行 CLI 或 MCP 服务器之前导出密钥：
bash
export PODFETCHERAPIKEY=pkliveyourkeyhere
可选覆盖项：
- - 非生产环境使用 PODFETCHERBASEURL
- 如果需要非默认标头名称，使用 PODFETCHERAPIKEY_HEADER
入口点
如果包已从 npm 全局安装，请使用以下二进制文件：
- - podfetcher
- podfetcher-mcp
如果您从本地检出工作，请从此目录运行命令或从其他工作区通过绝对路径引用这些文件：
- - CLI：node src/cli.js
- MCP 服务器：node src/mcp.js
- SDK 导入：./src/sdk.js
CLI 命令
搜索节目
bash
podfetcher shows search --q <查询> [--limit ] [--cursor <游标>] [--json]
- - --q 为必填项
- 返回包含 showId、title 和 author 的 items[]
- 如果存在，将 nextCursor 传入 --cursor 以获取下一页
列出剧集
bash
podfetcher shows episodes --show-id [--from ] [--to ] [--since ] [--order-by publishedAt] [--order asc|desc] [--limit ] [--cursor <游标>] [--json]
- - --show-id 为必填项
- 返回包含 episodeId、publishedAt、title 和 transcriptStatus 的 items[]
获取文字记录
bash
podfetcher transcripts fetch --episode-id [--wait] [--poll-interval-ms <毫秒>] [--wait-timeout-ms <毫秒>] [--idempotency-key <密钥>] [--json]
- - --episode-id 为必填项
- 不使用 --wait 时，API 可能返回包含 jobId 和 status=PROCESSING 的排队任务
- 使用 --wait 时，客户端会轮询直到文字记录就绪或超时
全局 CLI 选项
- - --api-key <密钥> 或 PODFETCHERAPIKEY 用于 Podfetcher 身份验证
- --base-url 或 PODFETCHERBASEURL 用于 API 端点覆盖
- --api-key-header <标头> 或 PODFETCHERAPIKEY_HEADER 用于标头覆盖
- --timeout-ms <毫秒>
- --json
典型工作流
bash
1. 查找节目
podfetcher shows search --q lex fridman --limit 3 --json
2. 列出最近的剧集
podfetcher shows episodes --show-id
--order-by publishedAt --order desc --limit 5 --json
3. 获取文字记录并等待完成
podfetcher transcripts fetch --episode-id --wait --json
MCP 服务器
通过 stdio 启动 MCP 服务器：
bash
podfetcher-mcp
可用工具：
- - searchshows
- listepisodes
- fetch_transcript
示例配置：
json
{
mcpServers: {
podfetcher: {
command: node,
args: [/绝对/路径/to/podfetcher-tools/src/mcp.js],
env: {
PODFETCHERAPIKEY: pklive...
}
}
}
}
错误处理
- - HTTP 错误格式化为 [HTTP <状态码>] <代码>: <消息>
- 缺少 API 密钥的错误会在发送请求前报告
- 错误时退出代码为 1，成功时为 0
