🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Podfetcher Tools
πŸ¦€ ClawHub

Podfetcher Tools

by @flohiwg

Search podcasts, browse episodes, and fetch podcast transcripts from Podfetcher using the bundled Node.js CLI, SDK, or MCP server.

Versionv0.5.1
Downloads668
#clawhub
TERMINAL
clawhub install podfetcher-tools

πŸ“– About This Skill

name: podfetcher-tools description: Search podcasts, browse episodes, and fetch podcast transcripts from Podfetcher using the bundled Node.js CLI, SDK, or MCP server. version: 0.5.1 metadata: openclaw: requires: env: - PODFETCHER_API_KEY - PODFETCHER_BASE_URL - PODFETCHER_API_KEY_HEADER bins: - node primaryEnv: PODFETCHER_API_KEY homepage: https://podfetcher.com

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 "" [--limit ] [--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  [--from ] [--to ] [--since ] [--order-by publishedAt] [--order asc|desc] [--limit ] [--cursor ] [--json]

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

    • Fetch transcript

    podfetcher transcripts fetch --episode-id  [--wait] [--poll-interval-ms ] [--wait-timeout-ms ] [--idempotency-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 or PODFETCHER_API_KEY for Podfetcher authentication
  • --base-url or PODFETCHER_BASE_URL for API endpoint override
  • --api-key-header
    or PODFETCHER_API_KEY_HEADER for header override
  • --timeout-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  --order-by publishedAt --order desc --limit 5 --json
    3. Fetch the transcript and wait for completion
    
podfetcher transcripts fetch --episode-id  --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 ] :
  • Missing API key errors are reported before the request is sent
  • Exit code is 1 on error and 0 on success

    • πŸ’‘ Examples

    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