Podfetcher Tools

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

Security Scan

The skill's code and runtime instructions match the stated purpose (podcast search and transcript fetch) and only require a Podfetcher API key and optional URL/header overrides; no unexpected network targets, binaries, or privileged behaviors were found, though the registry metadata slightly misstates which env vars are required.

Purpose & Capability

Name/description (search shows, list episodes, fetch transcripts) matches the included CLI, SDK, and MCP server code. Required binary 'node' and an API key are appropriate for this functionality.

Instruction Scope

SKILL.md instructs only about using the CLI/SDK/MCP with Podfetcher; runtime instructions and code only read Podfetcher-related env vars or command-line flags and communicate with the Podfetcher API. No instructions request unrelated files, system credentials, or external endpoints beyond the Podfetcher API.

Install Mechanism

No install spec is provided (instruction-only install), and the package includes source files but does not attempt to download or install arbitrary binaries. This is low-risk for installation mechanism.

Credentials

Primary credential PODFETCHER_API_KEY is appropriate. The registry metadata lists PODFETCHER_BASE_URL and PODFETCHER_API_KEY_HEADER as required env vars, but the SKILL.md and code treat those as optional overrides (with sensible defaults). This metadata-versus-code mismatch is minor but should be clarified.

Persistence & Privilege

always:false and normal model invocation are set. The skill does not request persistent system-wide privileges or modify other skills. The MCP server will expose tools over stdio as expected for an MCP plugin.

Assessment

This skill appears to do what it claims: it uses Node, accepts a Podfetcher API key, and talks to the Podfetcher API (default https://api.podfetcher.com). Before installing: 1) Be aware you must provide a Podfetcher API key—treat that key like a secret. 2) The registry metadata lists two extra env vars (PODFETCHER_BASE_URL, PODFETCHER_API_KEY_HEADER) as required, but the code treats them as optional overrides; verify which env vars your environment needs. 3) The MCP server enables an agent to call the API using whatever API key you supply—only provide a key with the minimum necessary permissions and avoid using highly privileged keys in untrusted agents. 4) If you need stronger assurance, inspect the included source (src/*.js) yourself or run the CLI in an isolated environment; there are no obvious hidden endpoints, network calls beyond the Podfetcher API, or escalations in the code.

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