pepys-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