> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Youka mit KI-Assistenten verwenden (MCP)

> Verbinde Claude Code, Cursor, Codex oder einen beliebigen MCP-Client mit Youka und erstelle Karaoke- und Lyric-Videos per Chat.

Youka hat einen MCP-Server. [MCP](https://modelcontextprotocol.io) (Model Context Protocol) ist der Standardweg, wie KI-Assistenten sich mit externen Tools verbinden. Sobald du ihn verbunden hast, kannst du deinen Assistenten Dinge fragen wie „erstelle ein Karaoke-Video aus \~/Music/song.mp3“, und er legt das Projekt in deinem Youka-Konto an, wartet bis es fertig ist und gibt dir den Editor-Link oder einen Download-Link.

Der Server funktioniert mit jedem MCP-Client, der Remote-Server (Streamable HTTP) mit einem benutzerdefinierten Header unterstützt, z. B. Claude Code, Cursor und Codex.

> [!NOTE]
>
> Offizielle Youka-Apps für ChatGPT und Claude kommen bald. Bis dahin nutze einen
> Client von dieser Seite mit einem Youka-API-Key.

## Was du brauchst

* Ein Youka-Konto mit Credits. Der MCP-Server nutzt dieselben Credits wie die Web-App. Siehe [Credits verstehen](https://docs.youka.io/de/web/understanding-credits.md).
* Einen Youka-API-Key. Erstelle ihn unter [online.youka.io/account](https://online.youka.io/account) unter **API keys**. Siehe [Authentifizierung](https://docs.youka.io/de/api/authentication.md).

Serverdetails:

| Einstellung | Wert |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> Dein API-Key gewährt vollen Zugriff auf dein Youka-Konto und dessen Credits.
> Halte ihn aus geteilten Dateien und Repositories heraus. Wenn ein Key
> geleakt ist, lösche ihn auf deiner Kontoseite und erstelle einen neuen.

## Assistent verbinden

> [tab] Claude Code
>
> Führe Folgendes in deinem Terminal aus und ersetze `YOUR_API_KEY` durch deinen Key:
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> Prüfe, dass es verbunden ist:
>
> ```bash theme={null}
> claude mcp list
> ```
>
> Du solltest `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected` sehen.
>
> Standardmäßig wird der Server nur für den aktuellen Ordner hinzugefügt. Füge `--scope user` hinzu, um Youka in jedem Ordner zu verwenden.

> [tab] Cursor
>
> Öffne `~/.cursor/mcp.json` (für jedes Projekt) oder `.cursor/mcp.json` in deinem Projektordner und füge den `youka`-Server hinzu:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Setze `YOUKA_API_KEY` in der Umgebung, aus der Cursor gestartet wird, oder ersetze `${env:YOUKA_API_KEY}` durch deinen Key. Öffne dann den MCP-Bereich in Cursors Einstellungen und prüfe, dass `youka` aktiviert ist.

> [tab] Codex
>
> Ausführen:
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> Oder füge das selbst zu `~/.codex/config.toml` hinzu:
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> Codex liest den Key aus der Umgebungsvariable `YOUKA_API_KEY`, also setze sie, bevor du Codex startest:
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> Führe `codex mcp list` aus, um zu prüfen, dass `youka` aktiviert ist.

> [tab] Other clients
>
> Jeder MCP-Client, der Remote-Server mit benutzerdefinierten Headers unterstützt, funktioniert. Verwende:
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transport:** Streamable HTTP (manchmal „HTTP“ genannt)
> * **Header:** `Authorization: Bearer YOUR_API_KEY`
>
> Der Server nutzt keine Sessions, daher sind keine weiteren Einstellungen nötig.

## Ausprobieren

Frag deinen Assistenten in normaler Sprache. Zum Beispiel:

```text theme={null}
Wie viele Youka-Credits habe ich?
```

```text theme={null}
Erstelle ein Karaoke-Video aus ~/Music/song.mp3. Transkribiere den Text automatisch.
```

```text theme={null}
Erstelle ein Lyric-Video aus ./demo.wav mit meinem "Neon"-Preset, exportiere es dann in 1080p und gib mir den Download-Link.
```

```text theme={null}
In meinem neuesten Youka-Projekt sollte die zweite Strophe "..." statt "..." sein. Korrigiere den Text und synchronisiere ihn erneut.
```

Eine typische Karaoke-Anfrage läuft so ab:

**1. Upload**

Der Assistent fragt Youka nach einem Upload-Link und lädt deine Datei hoch.
Das Hochladen ist kostenlos.

**2. Kosten prüfen**

Er prüft, wie viele Credits das Projekt verbrauchen wird, und vergleicht das
mit deinem Kontostand.

**3. Projekt erstellen**

Youka entfernt die Vocals und synchronisiert den Text. Das dauert ein paar
Minuten. Der Assistent prüft den Status, bis das Projekt bereit ist.

**4. Bearbeiten oder exportieren**

Du bekommst einen Link, um das Projekt im Youka-Editor zu öffnen. Wenn du
nach der Videodatei fragst, exportiert der Assistent sie und gibt dir einen
Download-Link.

Das Erstellen eines Projekts rendert nie von selbst ein Video. Du entscheidest, wann du exportierst, damit du den Text oder Stil vorher noch korrigieren kannst – entweder im Chat oder im [Youka-Editor](https://docs.youka.io/de/web/using-studio.md).

## Was der Assistent tun kann

| Tool | Was es macht | Uses credits |
| - | - | - |
| `get_account` | Zeigt dein Konto, deinen Credit-Saldo und Upload-Limits. | No |
| `list_presets` | Listet deine gespeicherten Stil-[presets](https://docs.youka.io/de/web/presets.md). | No |
| `prepare_upload` | Erstellt einen Upload-Link für eine Audio- oder Videodatei auf deinem Computer. | No |
| `quote_project` | Zeigt, was ein neues Projekt kosten wird. | No |
| `create_karaoke_video` | Erstellt aus einer Datei ein bearbeitbares Karaoke-Projekt (Vocals entfernt, Text synchronisiert). | Yes |
| `create_lyric_video` | Erstellt aus einer Datei ein bearbeitbares Lyric-Video-Projekt (Originalaudio, Text synchronisiert). | Yes |
| `list_projects` | Listet deine Projekte, neueste zuerst. | No |
| `get_project` | Zeigt den Status eines Projekts (processing, ready oder failed), Text, Stems, Exporte und Editor-Link. | No |
| `sync_lyrics` | Synchronisiert korrigierten Text erneut oder transkribiert den Song erneut. | Yes |
| `get_task` | Zeigt den Status einer Textsynchronisation. | No |
| `quote_export` | Zeigt, was ein Export kosten wird. | No |
| `export_video` | Rendert das Projekt so, wie es aktuell gespeichert ist, inkl. deiner Änderungen im Editor. | Yes |
| `get_export` | Zeigt den Status eines Exports und, wenn er fertig ist, einen Download-Link. | No |

## Credits und Sicherheit

* **Gleiche Credits wie die Web-App.** Projekte erstellen, Texte erneut synchronisieren und Exporte kosten genauso viel wie auf [online.youka.io](https://online.youka.io).
* **Kosten werden zuerst geprüft.** Wenn du nicht genug Credits hast, lehnt Youka die Anfrage ab und sagt das. Es wird nichts berechnet.
* **Keine doppelten Abbuchungen.** Wenn der Assistent eine Anfrage nach einem Timeout erneut versucht, erkennt Youka den Retry und liefert das ursprüngliche Ergebnis zurück, statt erneut zu berechnen.
* **Credits werden in Youka gekauft.** Der Assistent kann keine Credits kaufen. Um mehr hinzuzufügen, siehe [Mehr Credits kaufen](https://docs.youka.io/de/web/buy-credits.md).
* **Bezahlte Tools laufen nur auf Anfrage.** Der Assistent ist so angewiesen, Projekte zu erstellen, Texte zu synchronisieren oder zu exportieren, nur wenn du darum bittest.

## Fehlerbehebung

> [accordion] 401 Unauthorized, or the server shows as failed
>
> Der API-Key fehlt oder ist ungültig. Prüfe, dass der Header exakt
> `Authorization: Bearer yk_...` ist, mit genau einem Leerzeichen nach `Bearer`
> und ohne zusätzliche Leerzeichen oder Anführungszeichen im Key. Wenn du den Key
> auf deiner Kontoseite gelöscht hast, erstelle einen neuen und aktualisiere
> deinen Client. Bei Codex- und Cursor-Setups, die `YOUKA_API_KEY` lesen, stelle
> sicher, dass die Variable in der Umgebung gesetzt ist, aus der die App
> gestartet wird.

> [accordion] Not enough credits
>
> Frage den Assistenten nach deinem Kontostand oder prüfe ihn auf
> [online.youka.io](https://online.youka.io). Dann [kaufe mehr
> credits](https://docs.youka.io/de/web/buy-credits.md) und frage erneut.

> [accordion] The project failed
>
> Bitte den Assistenten, das Projekt zu zeigen. Es enthält den Fehler. Stelle
> sicher, dass die Datei ein unterstütztes Audio- oder Videoformat hat und
> innerhalb der Upload-Limits liegt, die dein Konto anzeigt.

> [accordion] The lyrics are wrong
>
> Teile dem Assistenten den korrekten Text mit und bitte ihn, erneut zu
> synchronisieren, oder öffne den Editor-Link und [bearbeite den Text](https://docs.youka.io/de/web/edit-lyrics.md)
> selbst. Exportiere danach erneut.

## Verwandte Dokumentation

* [AI agents](https://docs.youka.io/de/agents.md) — die Youka-CLI und Skill aus einem Agenten verwenden
* [Authentication](https://docs.youka.io/de/api/authentication.md) — API-Keys erstellen und verwenden
* [Credits verstehen](https://docs.youka.io/de/web/understanding-credits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.