{"id":50377477,"url":"https://github.com/jonathanmoore/tldl","last_synced_at":"2026-05-30T10:30:32.819Z","repository":{"id":354245350,"uuid":"1222785162","full_name":"jonathanmoore/tldl","owner":"jonathanmoore","description":"TLDR for podcasts. MCP server that returns YouTube and Spotify podcast transcripts as markdown — using platform auto-captions, no LLM transcription.","archived":false,"fork":false,"pushed_at":"2026-04-27T19:32:17.000Z","size":122,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T20:13:20.102Z","etag":null,"topics":["claude","claude-code","mcp","model-context-protocol","podcast","python","railway","spotify","transcript","transcription","youtube"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonathanmoore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T17:50:32.000Z","updated_at":"2026-04-27T19:32:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jonathanmoore/tldl","commit_stats":null,"previous_names":["jonathanmoore/tldl"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jonathanmoore/tldl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanmoore%2Ftldl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanmoore%2Ftldl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanmoore%2Ftldl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanmoore%2Ftldl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonathanmoore","download_url":"https://codeload.github.com/jonathanmoore/tldl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanmoore%2Ftldl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33689564,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","mcp","model-context-protocol","podcast","python","railway","spotify","transcript","transcription","youtube"],"created_at":"2026-05-30T10:30:30.029Z","updated_at":"2026-05-30T10:30:32.802Z","avatar_url":"https://github.com/jonathanmoore.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TLDL — Too Long; Didn't Listen\n\nA small MCP server that turns a YouTube, Spotify, or Apple Podcasts URL into a markdown transcript using the platforms' own auto-captions — no LLM transcription, no audio download. Runs locally on your own machine over stdio.\n\n\u003e **Too Long; Didn't Listen. Your AI did.**\\\n\u003e Useful for note-taking, summaries, or just talking to Claude about a podcast you skipped.\n\n## Quickstart\n\nOpen this repo in [Claude Code](https://claude.com/claude-code) and say:\n\n\u003e help me get this set up\n\nOr run `/setup`. The setup skill walks you through local install and testing.\n\n## What it does\n\nOne MCP tool:\n\n```\nget_transcript(url, language=\"en\", include_timestamps=False) -\u003e markdown\n```\n\n- **YouTube URLs** (`youtube.com/watch`, `youtu.be`, `/shorts/`, `/embed/`, `/live/`) — fetches manual or auto-generated captions and renders coalesced paragraphs with YAML frontmatter (title, channel, duration, language, fetched_at, etc.).\n- **Spotify episode URLs** (`open.spotify.com/episode/...`) — Spotify has no public transcript API, so the server resolves the episode title via Spotify's oEmbed endpoint, finds the same upload on YouTube via search, and fetches captions there. Works for podcasts that double-post. Spotify-exclusives return a clear error naming the best guess so you can decide whether to find an alternate source.\n- **Apple Podcasts URLs** (`podcasts.apple.com/.../id\u003cshow\u003e?i=\u003cepisode\u003e`) — same pattern as Spotify but via the public iTunes Lookup API to get the episode title. Apple-exclusives won't work; very old episodes (outside the most recent 200 for a show) return a clear \"out of lookup window\" error.\n- Optional `include_timestamps=true` adds `## [MM:SS]` section markers every 5 minutes.\n\n## How it works\n\nClaude Code spawns the Python server over stdio when you start a session and shuts it down when the session ends. No port, no token, no second terminal — the process boundary is the trust boundary.\n\n### Why local-only\n\nYouTube blocks transcript requests from cloud/datacenter IPs, and paid residential-proxy workarounds aren't worth their monthly cost for a single-user tool. Run TLDL from a residential connection — corporate egress, datacenter IPs, and most VPNs will also get blocked.\n\n## Limitations\n\n- **Local only.** Run TLDL from a residential connection; cloud hosting isn't supported.\n- **Platform-exclusive content** won't work — for Spotify (some Joe Rogan, Gimlet, Spotify Originals) and Apple Podcasts (Apple-exclusives) there's no YouTube version to fall back to. Error message names the best guess so you can decide.\n- **Apple Podcasts lookup window** is the most recent 200 episodes per show (iTunes Lookup limit). Older episodes return an \"out of lookup window\" error.\n- **Caption-disabled videos** return a clear \"captions disabled\" error.\n- **Caption quality varies** with audio quality and accent. The server can't fix bad source captions.\n- The transcript libraries (`youtube-transcript-api`, `yt-dlp`) reverse-engineer YouTube's endpoints. YouTube changes them periodically; bump those deps when things start failing.\n\n## Project layout\n\n```\n.\n├── pyproject.toml           # uv-managed deps\n├── uv.lock\n├── .env.example             # LOG_LEVEL\n├── .gitignore\n├── CLAUDE.md                # project rules for Claude Code agents\n├── README.md\n└── src/tldl/\n    ├── __init__.py\n    ├── markdown.py          # frontmatter + paragraph coalescing\n    ├── youtube.py           # video_id parse + transcript fetch + yt-dlp metadata\n    ├── resolver.py          # shared YouTube search + rapidfuzz scoring (used by Spotify + Apple)\n    ├── spotify.py           # oEmbed → resolver\n    ├── apple.py             # iTunes Lookup → resolver\n    └── server.py            # FastMCP app, get_transcript tool, stdio entrypoint\n```\n\n## Credits\n\nThis project would not exist without:\n\n- **[youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api)** by [@jdepoix](https://github.com/jdepoix) — does the entire transcript-fetching layer.\n- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — YouTube metadata extraction and the `ytsearch1:` fallback used to resolve Spotify episodes to YouTube.\n- **[FastMCP](https://gofastmcp.com)** — the MCP server framework.\n- **[rapidfuzz](https://github.com/rapidfuzz/RapidFuzz)** — fuzzy string matching for Spotify→YouTube confidence scoring.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanmoore%2Ftldl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonathanmoore%2Ftldl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanmoore%2Ftldl/lists"}