Skip to main content
Glama
Sign In
pepys-mcp

pepys-mcp

by ankurmans
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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.

Related MCP server: @scriptivox/mcp-server

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

Available Tools

9 tools
export_transcriptExport a transcriptA
Read-onlyIdempotent

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.)

Inputs: format (required), job_id (required), word_level.

get_credit_balanceCheck credit balanceA
Read-onlyIdempotent

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.

Inputs: no named parameters.

get_transcriptionGet transcription resultA
Read-onlyIdempotent

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'.

Inputs: job_id (required), wait_ms.

list_podcast_episodesList podcast episodesA
Read-onlyIdempotent

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.

Inputs: feed_url (required), limit.

list_transcriptionsList recent transcriptionsA
Read-onlyIdempotent

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.

Inputs: limit, status.

search_transcriptSearch within a transcriptA
Read-onlyIdempotent

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.

Inputs: query (required), job_id (required), whole_word, max_results, +2 more.

transcribeTranscribe audio/videoA
Idempotent

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.

Inputs: url, diarize, quality, summary, +7 more.

transcribe_podcast_feedBatch-transcribe a podcast feedA
Idempotent

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).

Inputs: feed_url (required), latest, diarize, idempotency_key.

upload_fileUpload local mediaA

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.

Inputs: path, filename, mime_type, bytes_base64.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.3/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct operation: uploading, transcribing (single/batch), fetching results, exporting, searching, listing, and credit checking. No functional overlap exists, allowing clear selection.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_transcription, list_transcriptions, upload_file). The verb transcribe is used alone for the primary action, but its derived tools (transcribe_podcast_feed) remain consistent.

    Tool Count5/5

    With 9 tools, the set is well-scoped for a transcription server. Each tool serves a distinct and necessary purpose without redundancy, fitting the typical optimal range of 3-15 tools.

    Completeness4/5

    The tool set covers the full transcription workflow: upload, transcribe (single and batch), fetch, export, search, and credit management. The only minor gap is the absence of a delete/reset tool, but this is not essential for the core use case.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers