# CleoLM

> CleoLM is a remote MCP server and REST API for timestamped YouTube and podcast transcripts. It searches 158 continuously synced channels (~4,000 new episodes a month, ~3.1M indexed passages) plus any YouTube video or podcast episode transcribed on demand. There is no server-side LLM: your model does the reasoning, and CleoLM returns source passages with deep links to the exact second.

## Endpoints

- MCP (Streamable HTTP, stateless, JSON responses): https://cleolm.com/mcp
- MCP with no sign-up (try it now): https://cleolm.com/mcp/open. No auth. Tools: search (public channels, up to 5 results), get_passage, list_channels. Limited to 10 calls a minute and 30 a day per network; connect /mcp for the full toolset.
- REST: https://cleolm.com/api/v2
- OpenAPI 3.1: https://cleolm.com/api/v2/openapi.json
- OAuth protected-resource metadata: https://cleolm.com/.well-known/oauth-protected-resource/mcp
- OAuth authorization-server metadata: https://cleolm.com/.well-known/oauth-authorization-server

## Auth

- OAuth 2.1 with PKCE S256, Dynamic Client Registration and Client ID Metadata Documents. Clients that support it only need the MCP URL.
- Or an API key: `Authorization: Bearer clm_live_...`. Users create and revoke keys at https://cleolm.com/developers. Keys are shown once, can be scoped to exclude ingest, and stop working within 60 seconds of revocation.
- Every account gets 50 free credits a month (search, transcripts, captioned YouTube). Pro and Max add a monthly allowance, podcasts, videos without captions and premium transcription. When credits or plan limits are hit, tools return credits_exhausted / upgrade_required with details.planOptionsUrl.
- Each cited segment includes `url` (the source at that second) and, for YouTube, `open_in_cleolm` (CleoLM's player at that moment with the transcript alongside).

## Tools

Item ids look like `yt:VIDEO_ID` or `pod:...`. Every passage carries a `timestamp` and a `url` deep link; cite that url.

- search(query, scope?="all"|"public"|"library", channels?, published_after?, published_before?, item_ids?, limit?<=25): semantic and keyword search across indexed channels and the user's library. 1 credit.
- discover(query, type?="youtube"|"podcast"|"podcast_episode", limit?<=20): find videos, shows or episodes on the open web. 1 credit.
- list_episodes(source, limit?<=50): latest uploads of a YouTube channel (handle, URL or UC id) or episodes of a podcast (RSS, Apple Podcasts or Spotify show URL). Free.
- get_transcript(id | url, cursor?, max_chars?, format?="text"|"segments"): full timestamped transcript, paginated (~30k characters per page). 0.2 credits per page. Returns not_ingested if the item must be ingested first.
- get_passage(id | url, at_seconds, before_seconds?, after_seconds?): transcript window around a moment. Free.
- ingest(url, quality?="standard"|"premium", wait_seconds?): transcribe a YouTube video or podcast episode into the user's library. Returns a job; poll get_job. "premium" uses high-accuracy ASR (Pro/Max). Already transcribed: 0 credits; captions: 4; podcast audio: 10/hr; ASR: 20/hr; AI video: 36/hr. The worst case is reserved up front and the difference refunded.
- get_job(job_id): status of an ingest job (queued, running, completed, failed). Poll every 15-30 s. Free.
- list_channels(query?): channels covered by search. Free.
- account(): plan, credits remaining, reset date and limits. Free. Call it after credits_exhausted or upgrade_required.
- show_player(id | url, moments[{seconds, label}], title?, channel?): renders an inline YouTube player in hosts that support MCP Apps (Claude, ChatGPT), with the cited moments as timestamps that seek the player. Call once per answer for the main video. Free.

Typical flow: search -> get_passage -> answer citing passage urls. For one specific video or episode: ingest -> get_job -> get_transcript.

## Errors

- `credits_exhausted` (HTTP 402): the hard cap was reached. Stop and tell the user; do not retry.
- `upgrade_required`: the account's plan has no agent access.
- `not_ingested`: call ingest first.

## Pricing

- Pro: $25/month, includes 1,000 credits.
- Max: $99/month, includes 5,000 credits.
- Credit packs: $20 for 1,000, $90 for 5,000. Prepaid, never auto-recharge. Spending is hard-capped by default.
- 1 credit = $0.02. Each search costs 1 credit.

## Links

- Overview and install instructions: https://cleolm.com/agents
- Keys, connected apps and credits: https://cleolm.com/developers
- Pricing: https://cleolm.com/pricing
- Privacy: https://cleolm.com/privacy
- Terms: https://cleolm.com/terms
- Support: support@cleolm.com