yoto-mcp

Lets Claude read and safely edit your Yoto MYO playlists and interactive cards. It's a local MCP server plus a Claude Code plugin (yoto) that adds skills, slash commands, a plan reviewer and a guard on writes.

• Cards by title. Cards are named the way the Yoto app shows them, and card ids never appear.

• Every write is plan, then apply. A plan shows a diff, warnings and lint. Apply checks that the card hasn't changed since, backs it up, writes, reads it back, and checks that tracks play.

• Interactive cards from a story graph. A compiler and a player simulator catch the gotos to nowhere, dead buttons and endless loops that fail silently on a real player.

• Spoken prompts on your machine. Local TTS with a pronunciation map, plus a speech-to-text check.

• Icons. Pixel-exact 16×16 icons drawn from character grids, and an icon chooser page.

It runs on your machine over stdio. Your Yoto tokens and the app's client secret stay in the macOS keychain, and no tool result ever contains them.

Install

1. Store the Yoto app's credentials and link your account(s) (once, in a terminal):

uvx --from git+https://github.com/earchibald/yoto-mcp yoto-mcp setup        # client id + secret → keychain
uvx --from git+https://github.com/earchibald/yoto-mcp yoto-mcp login Eugene  # browser login, linked as "Eugene"
uvx --from git+https://github.com/earchibald/yoto-mcp yoto-mcp login Family  # optional second family account

The first account you link becomes the default; change it with yoto-mcp default <name>. Login listens on the app's registered callback, http://localhost/oauth/callback by default (use setup --redirect-uri … to change it).

2. Add the plugin to Claude Code:

/plugin marketplace add earchibald/yoto-mcp
/plugin install yoto@yoto-mcp

The plugin starts the server with uvx, so you need uv. Without the plugin, any MCP client can run the server directly: claude mcp add yoto -- uvx --from git+https://github.com/earchibald/yoto-mcp yoto-mcp serve.

Optional, for spoken prompts: ollama with a speech model (ollama pull phonon), ffmpeg, and mlx_whisper or whisper for the transcript check.

Related MCP server: claude-projects-mcp-server

Use it

You can also just ask: "add a spoken title before each book on Hilo Books 4-8".

Tools

There are also resources (yoto://schema/story-graph, yoto://docs/interactive, card JSON, outline and Mermaid graph) and three prompts (book-selector, add-title-tracks, audit-card).

Safety

yoto_card_apply refuses a plan if any of these holds:

• the card changed after the plan was made

• the card's title changed

• the account doesn't own the card

• the plan is older than 30 minutes

• the plan has lint errors, such as another account's media refs

It saves a backup to ~/.yoto/backups/ (the last 20 per card), writes, re-reads, compares, and makes ranged GETs on the first, last and changed tracks. Each apply is logged to ~/.yoto/changes.log. The plugin's PreToolUse hook also blocks an apply without a valid plan, and asks you to confirm every write with a one-line summary.

Interactive cards

Claude writes a small graph; the compiler does the rest:

{"nodes": [
  {"id": "q", "type": "choice", "tracks": [{"audio": "yoto:#…"}], "left": "cave", "right": "woods"},
  {"id": "cave", "type": "end", "tracks": [{"audio": "yoto:#…"}]},
  {"id": "woods", "type": "end", "tracks": [{"audio": "yoto:#…"}]}],
 "expect": [{"presses": ["left"], "plays": ["q", "cave"]}]}

Node order is chapter (dial) order. The compiler gives every chapter a unique key and emits onEnd/onLhb/onRhb events. It sets the interactive config: no autoadvance, dial skipping on, and resumeTimeout: 1 so the card starts over. Then the simulator walks every path and checks the declared expect walks before any plan is made.

Icon chooser

From Claude Code, the chooser opens in your browser on a loopback port with a one-time token. In an MCP Apps host such as Claude Desktop, it renders inline (ui://yoto/icon-chooser). Picks come back as a plan of set_icon ops.

Live checks

These are open questions from the design. Each one writes to the default account and cleans up after itself.

uvx --from git+https://github.com/earchibald/yoto-mcp yoto-mcp check icons    # autoConvert=false icon round-trip, pixel-exact?
uvx --from git+https://github.com/earchibald/yoto-mcp yoto-mcp check resume   # is resumeTimeout: 0 accepted?

Develop

uv run --extra dev pytest
claude --plugin-dir . plugin details yoto     # load the plugin from this checkout

Tests run against tests/fake_yoto.py, which mimics what the real API did during the Hilo work:

• /content is owner-only, and /card returns signed URLs

• foreign refs fail with 400

• known uploads get a null upload URL

• transcoding is async

• refresh tokens rotate

mcp is pinned below 2, because 2.x renamed FastMCP.