About Pepys
Pepys is an MCP server for agents that need audio and video transcription through the Pepys API. It supports speaker labeling, timestamped exports, and URL-based media ingestion.
Key features
- 01Transcribe audio and video
- 02Label speakers and timestamps
- 03Ingest media from URLs
- 04Batch podcast feed transcription
- 05Export SRT, VTT, TXT, MD, JSON
- 06Search and ask about transcripts
Use cases
- 01Transcribe a YouTube video or podcast
- 02Create timestamped caption files
- 03Find a phrase in a long transcript
MCP support
Exposes transcription tools, a finished-transcript resource, and a transcribe_and_summarize prompt to MCP clients. It runs locally over stdio or can use Pepys's hosted OAuth connector.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://pepys.co/api/mcpclaude mcp add --transport http pepys https://pepys.co/api/mcp{"mcpServers":{"pepys":{"type":"http","url":"https://pepys.co/api/mcp"}}}Open in Cursor{"servers":{"pepys":{"type":"http","url":"https://pepys.co/api/mcp"}}}Open in VS Code{"mcpServers":{"pepys":{"type":"http","url":"https://pepys.co/api/mcp"}}}{"mcpServers":{"pepys":{"serverUrl":"https://pepys.co/api/mcp"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
Tools
9| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | No | Public media URL: a file, YouTube video, podcast RSS feed or episode, or a Drive/Dropbox share. Provide EITHER url OR file_ref. |
| file_ref | string | No | A file_ref from upload_file, for local media. Provide EITHER url OR file_ref. |
| language | string | No | BCP-47 hint, e.g. 'en'. Omit to auto-detect. |
| diarize | boolean | No | Label who said what. Paid capability; a non-entitled account gets an upgrade message. |
| summary | boolean | No | Also generate an AI summary. |
| chapters | boolean | No | Also generate chapters. |
| translate_to | string | No | BCP-47 target to translate the transcript into. |
| quality | enum | No | fast | accurate |
| episode_guid | string | No | Pick one podcast-feed episode by guid. Only with a feed url; mutually exclusive with episode_index. |
| episode_index | integer | No | Pick one podcast-feed episode by position (0 = newest). Mutually exclusive with episode_guid. |
| idempotency_key | string | No | Make retries safe; the same key returns the same job. |
Details
From the project READMEpepys-mcp
Transcription for AI agents, by Pepys.
The Pepys transcription MCP server – give any MCP-speaking agent (Claude, ChatGPT, Cursor, Gemini, open-source agents) speaker-labeled, timestamped transcription of audio and video: diarization, SRT/VTT captions, paste-a-link ingestion (YouTube, podcasts, Drive/Dropbox), batch, and word-level export. Pepys never trains on your audio.
The package runs locally over stdio with a Pepys API key. Pepys also hosts a production OAuth connector at https://pepys.co/api/mcp for compatible remote-MCP clients.
Install & configure
Requires Node ≥ 18 and a Pepys API key (pk_live_…) from https://pepys.co/developers. Some capabilities require an account entitlement.
Run it with npx (no global install):
Claude Desktop / Claude Code – claude_desktop_config.json (or claude mcp add):
{
"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).
Claude Code plugin
This repo also bundles a Claude Code plugin that points at the hosted OAuth connector (no API key needed):
/plugin marketplace add ankurmans/pepys-mcp
/plugin install pepys
The first tool call opens an OAuth sign-in to your Pepys account. See skills/pepys/SKILL.md for what it can do and example prompts.
Tools
| Tool | What it does |
|---|---|
transcribe | Start a transcription from a url (file / YouTube / podcast / Drive) or a file_ref. Options: diarize (entitlement required), 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_guids. |
transcribe_podcast_feed | Batch a whole feed (or latest N). Account entitlement required. |
export_transcript | Export SRT / VTT / TXT / MD / JSON. Word-level timing requires an account entitlement. (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). |
ask_transcription | Answer a question about a transcript with server-verified, citation-backed claims only. |
get_credit_balance | Remaining transcription balance and entitlement state. |
Also exposes finished transcripts as the resource pepys://transcription/{id} and a transcribe_and_summarize prompt.
Account limits over MCP: 402 returns an insufficient-balance result, while unavailable capabilities return a clear entitlement result and a supported fallback where one exists. The MCP server does not initiate purchases or link to checkout.
Develop
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. Learn more at pepys.co · MCP server · Developer docs.
License
MIT
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.