FloHiwg/podfetcher-tools

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+
• PODFETCHER_API_KEY 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.
2. Generate an API key from the Podfetcher dashboard.
3. Export the key before running the CLI or MCP server:

export PODFETCHER_API_KEY="pk_live_your_key_here"

Optional overrides:

• PODFETCHER_BASE_URL for non-production environments
• PODFETCHER_API_KEY_HEADER if you need a non-default header name

Entry Points

If the package is installed globally from npm, use these binaries:

• podfetcher
• podfetcher-mcp

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: node src/cli.js
• MCP server: node src/mcp.js
• SDK import: ./src/sdk.js

CLI Commands

Search shows

podfetcher shows search --q "<query>" [--limit <n>] [--cursor <cursor>] [--json]

• --q is required
• Returns items[] with showId, title, and author
• If present, pass nextCursor into --cursor for the next page

List episodes

podfetcher shows episodes --show-id <showId> [--from <iso>] [--to <iso>] [--since <iso>] [--order-by publishedAt] [--order asc|desc] [--limit <n>] [--cursor <cursor>] [--json]

• --show-id is required
• Returns items[] with episodeId, publishedAt, title, and transcriptStatus

Fetch transcript

podfetcher transcripts fetch --episode-id <episodeId> [--wait] [--poll-interval-ms <ms>] [--wait-timeout-ms <ms>] [--idempotency-key <key>] [--json]

• --episode-id is required
• Without --wait, the API may return a queued job with jobId and status=PROCESSING
• 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
• --base-url <url> or PODFETCHER_BASE_URL for API endpoint override
• --api-key-header <header> or PODFETCHER_API_KEY_HEADER for header override
• --timeout-ms <ms>
• --json

Typical Workflow

# 1. Find a show
podfetcher shows search --q "lex fridman" --limit 3 --json

# 2. List recent episodes
podfetcher shows episodes --show-id <showId> --order-by publishedAt --order desc --limit 5 --json

# 3. Fetch the transcript and wait for completion
podfetcher transcripts fetch --episode-id <episodeId> --wait --json

MCP Server

Start the MCP server over stdio:

podfetcher-mcp

Available tools:

• search_shows
• list_episodes
• fetch_transcript

Example config:

{
  "mcpServers": {
    "podfetcher": {
      "command": "node",
      "args": ["/absolute/path/to/podfetcher-tools/src/mcp.js"],
      "env": {
        "PODFETCHER_API_KEY": "pk_live_..."
      }
    }
  }
}

Error Handling

• HTTP errors are formatted as [HTTP <status>] <code>: <message>
• Missing API key errors are reported before the request is sent
• Exit code is 1 on error and 0 on success