bperkinspdx/yoto-mcp-server

Yoto MCP Server

A Model Context Protocol (MCP) server that bridges Warp AI and the Yoto API, enabling seamless audio uploads and MYO card creation directly from your terminal.

Features

• 🔐 OAuth Device Flow Authentication - Secure authentication with Yoto API
• 🎵 Audio Upload - Upload MP3 files to Yoto with automatic transcoding
• 📦 MYO Card Creation - Automatically create Make Your Own cards
• 🔄 Token Management - Automatic token refresh and storage
• 🚀 Native Warp Integration - Use Yoto tools directly in Warp Agent Mode

Prerequisites

• Node.js 18+
• A Yoto account
• Warp terminal with Agent Mode enabled

Installation

1. Clone or download this repository:

cd yoto-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Add to Warp MCP Settings

Add this server to your Warp MCP configuration file (usually ~/.config/warp/mcp_config.json or similar):

{
  "mcpServers": {
    "yoto": {
      "command": "node",
      "args": [
        "/absolute/path/to/yoto-mcp-server/dist/index.js"
      ]
    }
  }
}

Or for global installation:

npm link

Then in your Warp MCP config:

{
  "mcpServers": {
    "yoto": {
      "command": "yoto-mcp-server"
    }
  }
}

Usage

Once configured, restart Warp and you'll have access to three new tools in Agent Mode:

1. Authenticate with Yoto

First, authenticate with your Yoto account:

In Warp Agent Mode:

Please authenticate with Yoto

Or explicitly:

Use the yoto-auth tool

The server will display a URL and code. Visit the URL in your browser, enter the code, and approve the connection.

2. Check Authentication Status

In Warp Agent Mode:

Check if I'm authenticated with Yoto

3. Upload Audio to Yoto

In Warp Agent Mode:

Upload the file /path/to/audio.mp3 to my Yoto player with title "My Audio Track"

The server will:

1. Upload the audio file to Yoto
2. Wait for transcoding (automatic conversion to Yoto-compatible format)
3. Create a new MYO card with the audio
4. Return the card ID

You can then link the card to a physical MYO card using your Yoto app or player.

4. List Your MYO Cards

In Warp Agent Mode:

List all my Yoto cards

Returns a list of all your MYO cards with their IDs and titles.

5. Get Card Details

In Warp Agent Mode:

Get details for Yoto card dyp9b

Returns detailed information about a specific card including chapter and track counts.

6. Add Track to Existing Card

In Warp Agent Mode:

Add /path/to/track2.mp3 to Yoto card dyp9b with title "Track 2"

Adds a new audio track to an existing MYO card as an additional chapter.

Example Workflow

User: Please authenticate with Yoto

[Server displays URL and code]
[User visits URL and approves]

✅ Successfully authenticated with Yoto API!

---

User: Upload hop-little-bunnies.mp3 to Yoto with title "Hop Little Bunnies"

[Server uploads and transcodes]

✅ Successfully uploaded audio to Yoto!

Card ID: dyp9b
Title: Hop Little Bunnies

You can now link this card to a physical MYO card using your Yoto app or player.

Available Tools

Configuration Storage

Authentication tokens are stored securely in ~/.yoto-mcp-config.json. The server automatically handles token refresh.

Development

Build

npm run build

Watch mode

npm run watch

Run directly

npm run dev

Troubleshooting

Authentication Issues

• Ensure you're visiting the correct URL and entering the code within the time limit
• Check that your Yoto account is active
• Try re-authenticating: the old token will be replaced

Upload Failures

• Verify the audio file path is absolute and accessible
• Ensure the file is in MP3 format
• Check file size (very large files may timeout during transcoding)

Token Expiry

• Tokens automatically refresh when expired
• If refresh fails, re-authenticate using yoto-auth

API Reference

This server uses the Yoto Developer API. For more information:

• Documentation: https://yoto.dev/api/
• MYO Cards Guide: https://yoto.dev/myo/uploading-to-cards/

License

MIT

Contributing

Contributions welcome! Please feel free to submit issues or pull requests.

Acknowledgments

• Built with the Model Context Protocol SDK
• Powered by the Yoto API
• Designed for Warp Terminal