# ankurmans/pepys-mcp [Health: Active]

**Category:** 🎙️ Speech-to-Text  
**Repository:** https://github.com/ankurmans/pepys-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 254  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ankurmans-pepys-mcp

## Description
Pay-once transcription for audio, video, and whole podcast feeds via Pepys. Transcribe a file or a pasted YouTube/podcast link, get speaker diarization, export SRT/VTT, search a transcript, and check credit balance. Hosted connector (OAuth, no API key) or npx pepys-mcp. 99+ languages.

## Tools
Capabilities this server exposes over MCP:

- **transcribe** — Transcribe hours-long audio or video into an accurate, speaker-labeled (diarized), timestamped transcript with correctly-timed SRT/VTT captions – work a general model can't do on a raw file. Accepts a file_ref from upload_file or a url (YouTube, podcast episode, RSS feed, Google Drive/Dropbox share). Audio is never used to train models. Returns { job_id, status }; fetch the result with get_transcription.
- **get_transcription** — Fetch a transcription by job_id: full text, per-speaker timestamped segments, summary, duration_seconds, billed_minutes, and language. Set wait_ms (up to 25000) to long-poll so short clips come back in one call; otherwise poll until status is 'done'.
- **upload_file** — Upload local audio/video the agent is holding (as base64 bytes or a file path) and get back a file_ref to pass to transcribe. Use this when the media has no public URL. Requires the Pepys R2 storage backend.
- **list_transcriptions** — List this account's recent transcription jobs with their job_id, status, title, and duration, so you can resume, fetch, or export an earlier result instead of re-transcribing.
- **list_podcast_episodes** — Given a podcast RSS feed or Apple Podcasts show URL, list its episodes (title, publish date, episode_guid, audio_url) so you can pick exactly which one to transcribe.
- **transcribe_podcast_feed** — Batch-transcribe a whole podcast feed in one call – fan out every episode, or the latest N, to individual jobs. Returns a set of job_ids. Paid capability (throughput/abuse gate).
- **export_transcript** — Export a finished transcript as SRT, VTT, TXT, Markdown, or JSON, with correct caption timings. Segment-level export is free; word-level-timed export (word_level:true) is a paid unlock. (DOCX/PDF are available in the Pepys web app.)
- **search_transcript** — Search inside a long transcript for a phrase and get back only the matching timestamped segments – locate a quote or topic in an hours-long recording without loading the whole transcript into context.
- **get_credit_balance** — Return the account's remaining transcription credits (in minutes) so you can check headroom before starting a large batch and avoid running out mid-run.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "pepys-mcp": {
    "command": "npx",
    "args": ["-y","pepys-mcp"],
    "env": {
      "PEPYS_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `PEPYS_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

# pepys-mcp

> Transcription for AI agents, by **[Pepys](https://pepys.co)** – pay-once audio & video transcription at **[pepys.co](https://pepys.co)**.

The **Pepys transcription MCP server** – give any MCP-speaking agent (Claude, ChatGPT, Cursor, Gemini, open-source agents) accurate, speaker-labeled, timestamped transcription of hours-long audio and video: diarization, correctly-timed SRT/VTT captions, paste-a-link ingestion (YouTube, podcasts, Drive/Dropbox), batch, and word-level export – work a general model can't do on a raw file. **Pepys never trains on your audio.**

Thin stdio wrapper over the Pepys [v1 REST API](https://pepys.co/developers). Phase-1 (BYO-key). OAuth/remote is on the roadmap.

## Install & configure

Requires **Node ≥ 18** and a Pepys API key (`pk_live_…`) from <https://pepys.co/developers>. **You get 60 free minutes on signup** – no card. Buy any pack once to unlock diarization, batch, and word-level export.

Run it with `npx` (no global install):

**Claude Desktop / Claude Code** – `claude_desktop_config.json` (or `claude mcp add`):

```json
{
  "mcpServers": {
    "pepys": {
      "command": "npx",
      "args": ["-y", "pepys-mcp"],
      "env": { "PEPYS_API_KEY": "pk_live_your_key_here" }
    }
  }
}
```

**Cursor** – `~/.cursor/mcp.json`, same shape. **Windsurf / other dev agents** – point them at `npx -y pepys-mcp` with `PEPYS_API_KEY` in the env.

Optional env: `PEPYS_API_BASE` (defaults to `https://pepys.co/api/v1`).

## Tools

| Tool | What it does |
|---|---|
| `transcribe` | Start a transcription from a `url` (file / YouTube / podcast / Drive) or a `file_ref`. Options: `diarize` (paid), `summary`, `chapters`, `translate_to`, `quality`, podcast `episode_guid`/`episode_index`. Returns `{ job_id, status }`. |
| `get_transcription` | Fetch a job by `job_id`; set `wait_ms:25000` to long-poll short clips to completion in one call. |
| `upload_file` | Upload local media (a `path` or `bytes_base64`) → a `file_ref` for `transcribe`. |
| `list_transcriptions` | Recent jobs (id, status, title, minutes). |
| `list_podcast_episodes` | Episodes of an RSS/Apple/Spotify feed, with `episode_guid`s. |
| `transcribe_podcast_feed` | Batch a whole feed (or latest N). **Paid.** |
| `export_transcript` | Export SRT / VTT / TXT / MD / JSON. Segment-level is free; `word_level:true` is a **paid** unlock. (DOCX/PDF: use the web app.) |
| `search_transcript` | Find a phrase in a long transcript → only the matching timestamped segments (no full-transcript context load). |
| `get_credit_balance` | Remaining credit minutes + whether Pro is unlocked. |

Also exposes finished transcripts as the resource `pepys://transcription/{id}` and a `transcribe_and_summarize` prompt.

**Billing over MCP:** two graceful prompts – `402` (out of minutes → top up at pepys.co/billing) and a Pro-feature upgrade message (diarization / batch / word-level → unlock with any one-time purchase). Segment exports, single transcription, links, and uploads are free on your minutes.

## Develop

```bash
npm install
npm run build      # tsc → dist/ (+ chmod the bin)
npm run smoke      # PEPYS_API_KEY=pk_live_… npm run smoke  – hits the live API to verify your key
```

## Publish

`npm run build && npm publish` (publishes `pepys-mcp`). Registry listings (MCP registry, mcp.so, Smithery, PulseMCP, Glama, `awesome-mcp-servers`) are submitted separately.

## About

Built by **[Pepys](https://pepys.co)** – pay-once, usage-based transcription for audio and video (no subscription, credits never expire). Learn more at **[pepys.co](https://pepys.co)** · [MCP server](https://pepys.co/mcp) · [Developer docs](https://pepys.co/developers) · [Pricing](https://pepys.co/pricing).

## License

MIT