tautau-mcp

An MCP (Model Context Protocol) stdio server that gives LLM clients — Claude Code, Claude Desktop, Codex, anything that speaks MCP — access to tautau transcription:

• YouTube links → transcript (captions-first, returns in seconds)
• Podcast / direct-audio URLs → transcript (server-side speech-to-text, long jobs poll automatically)
• Local audio files (mp3/wav/m4a/ogg/webm/mp4, up to 25MB) → transcript
• Recording evidence → bounded session transcripts, diagnostics, and collected assets
• Asset library → authenticated asset metadata and safe inline text previews

No API key, no account: usage is anonymous and quota-tracked per IP by the tautau service (5 lifetime URL transcripts, 5 lifetime dictations). When you hit the wall the tools say so and point at signup / pricing — a free account gets a daily allowance.

30-second install

Node.js >= 18 required. The server runs via npx — there is nothing to install globally.

One-shot installer (detects Claude Code / Codex / Claude Desktop and wires them up, prompting per client):

curl -fsSL https://tautau.xyz/mcp/install.sh | bash
# or from this repo:
bash mcp/install.sh --yes

Or configure your client by hand:

Claude Code

claude mcp add tautau -- npx -y tautau-mcp

Claude Desktop — edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Linux: ~/.config/Claude/):

{
  "mcpServers": {
    "tautau": {
      "command": "npx",
      "args": ["-y", "tautau-mcp"]
    }
  }
}

Codex — append to ~/.codex/config.toml:

[mcp_servers.tautau]
command = "npx"
args = ["-y", "tautau-mcp"]

Restart the client after editing config. Verify with get_quota (see below).

Environment

| Variable | Default | Purpose | | --- | --- | --- | | TAUTAU_API_BASE | https://tautau.xyz | API base URL — only override for self-hosted/dev deployments | | TAUTAU_AUTH_FILE | ~/.config/tautau/auth.json | Override the local Firebase session file location |

Tools

transcribe_url

Transcribe a YouTube video, podcast episode, or direct audio URL.

| Argument | Type | Required | Notes | | --- | --- | --- | --- | | url | string | yes | Full https:// link | | language | string | no | BCP-47 hint, e.g. "en" | | cleanup | boolean | no | AI polish: punctuation, filler removal |

YouTube resolves from captions inline; audio/podcast links return pending and the server polls every 3s for up to 6 minutes. Long transcripts are returned in full.

Example: "Transcribe https://www.youtube.com/watch?v=UF8uR6Z6KLc" →

Title: Steve Jobs' 2005 Stanford Commencement Address
Duration: 15:04
Source: youtube-captions
Quota: 1/5 transcripts used on the anonymous plan

[full transcript text…]

transcribe_audio

Transcribe a local audio file.

| Argument | Type | Required | Notes | | --- | --- | --- | --- | | filePath | string | yes | Absolute path; mp3/wav/m4a/ogg/webm/mp4, max 25MB | | language | string | no | BCP-47 hint | | cleanup | boolean | no | AI polish |

Example: "Transcribe the voice memo at /Users/me/recordings/idea.m4a"

get_quota

No arguments. Returns the current quota snapshot for your IP: plan, used/limit, remaining, and reset time.

get_scan

Fetch a page-scan debug bundle by its trace id.

| Argument | Type | Required | Notes | | --- | --- | --- | --- | | scanId | string | when signed out | The 32-char hex trace id the extension popup shows after Scan this page; omit when signed in to get your latest scan |

Returns the scan meta (page, status, bundle size, timings), the service-side RPC trace (every API call the extension made while the scan ran, with latencies), and a digest of the captured bundle: console errors, failed network requests (with error response bodies), pinned elements, voice/agent actions, the page outline, and the extension's own log. Signed out, the scan id is a capability — anyone holding it can read the scan. Signed in (auth_login), reads go through the owner API.

Example: "Fetch tautau scan 9f2c… and tell me why the voice command didn't click the button"

get_recording

Read a public recording capability and its session evidence. The required recordingId is a 32-character lowercase hex id. The response includes the recording link, transcript, collection references, and bounded console, network, interaction, and pin evidence. Signed bundle URLs are fetched for the request and are never returned or saved.

list_assets

List the authenticated asset library, newest first.

| Argument | Type | Required | Notes | | --- | --- | --- | --- | | limit | number | no | Integer from 1 to 200; defaults to 50 |

get_asset

Read one authenticated asset using its 32-character lowercase hex assetId. Ready assets include a current media URL. Text-like files (text/plain, text/csv, application/json, application/xml, and image/svg+xml) are included inline only when they are no larger than 32KiB. Binary data is never embedded in an MCP response.

auth_login / auth_status / auth_logout

auth_login opens your browser for Google/email sign-in (same Firebase auth as the web app). The page hands the tokens to a loopback callback the MCP server is listening on — tokens never leave your machine. The session is stored at TAUTAU_AUTH_FILE or, by default, ~/.config/tautau/auth.json (mode 0600) and auto-refreshes. auth_status shows who you're signed in as; auth_logout deletes the session. list_assets and get_asset require this session.

list_scans

Requires auth_login. Lists your page scans, newest first (id, status, time, size, page). Pair with get_scan to debug: "List my tautau scans and pull the latest one — why did the page command fail?"

suggest_page_action

Interpret a natural-language page command ("click sign in", "type hello into search") against a page snapshot and return ONE server-validated action (click/input/select/scroll/none, index bounds-checked — out-of-range coerces to none with a reason, never an error).

| Argument | Type | Required | Notes | | --- | --- | --- | --- | | command | string | yes | 1–500 chars | | scanId | string | no | Build the snapshot from this scan's bundle (preferred — same source triage uses) | | snapshot | string | no | Page text with [n] prefixes, ≤32KiB (when no scanId) | | url / title | string | no | Page overrides |

Requires auth_login (page actions are uid-gated). Execute the returned action in your own browser, then re-scan and verify with diff_scans — the full loop is worked in docs/agent-loop.md in the repo.

diff_scans

Diff two scan captures for QA: changed pages, added/removed headings and assets, new vs resolved console errors and failed requests. Anonymous (public capabilities).

| Argument | Type | Required | Notes | | --- | --- | --- | --- | | scanIdA | string | yes | Before scan (32-char hex) | | scanIdB | string | yes | After scan (32-char hex) |

Quotas & anonymity

• The server sends no credentials; tautau tracks anonymous usage by client IP.
• Anonymous: 5 lifetime YouTube/URL transcripts + 5 lifetime audio dictations.
• Free account: 5 URL transcripts/day + 15 min of audio per month — sign up.
• Paid plans raise the audio-minute pool — pricing.
• On HTTP 429 the tools return a readable message with used/limit/reset time and the relevant link. On 403 sign_up_required (anonymous audio-link jobs) they explain that a free account is needed.
• Anonymous transcripts are never persisted server-side; nothing is saved to a history.

Development

cd mcp
npm install
npm run build
npm run smoke   # boots the server over stdio and runs read-only probes

From the repo root: task mcp:smoke.

The typed recording and asset modules compile to dist/ with strict NodeNext TypeScript. npm start builds before launching, and npm publish builds through prepublishOnly. The smoke test never burns transcribe quota. It only lists tools and calls get_quota plus safe not-found/auth checks.

Marketplace listings

Smithery

1. smithery.yaml ships in this package (stdio, no required config).
2. Push the repo, then at smithery.ai choose Publish server → GitHub, point it at this repo and set the server root to mcp/.
3. Smithery builds from smithery.yaml; the optional tautauApiBase config field maps to TAUTAU_API_BASE.
4. Verify the deployment's tool list shows transcribe_url, transcribe_audio, get_quota, then publish.

Official MCP servers registry

1. Fork modelcontextprotocol/servers.
2. Add a row to the Third-Party Servers section of the README: tautau — YouTube, podcast, and local-audio transcription (tautau.xyz), linking https://github.com/castlemilk/tautau/tree/main/mcp.
3. Keep the list alphabetized and match the existing row format (name, one-line description, link).
4. Open the PR against main; CI checks formatting only.

License

MIT