sync. labs

npx add-mcp 'https://mcp.sync.so/mcp'

sync. MCP-Server

Verbinde deinen KI-Agenten mit sync., um Videos lippensynchron zu machen, sie in andere Sprachen zu übersetzen und zu synchronisieren, Stimmen zu klonen und Assets sowie Projekte über einen Chat oder eine Coding-Sitzung zu verwalten.

sync. hostet diesen Server unter https://mcp.sync.so/mcp. Du meldest dich mit deinem sync.-Konto an, daher musst du nichts installieren und keinen API-Schlüssel kopieren. Jeder Merge in main dieses Repositorys wird dort bereitgestellt.

Agent verbinden

ChatGPT

Öffne sync. in ChatGPT und verbinde dein Konto. In ChatGPT wird sync. Studio ebenfalls im Chat geöffnet.

Claude (claude.ai und Claude Desktop)

1. Öffne Settings → Connectors und wähle Add custom connector.
2. Gib ihm den Namen sync. und setze die URL auf https://mcp.sync.so/mcp.
3. Klicke auf Connect und melde dich bei sync. an.

Claude Code

claude mcp add --transport http sync https://mcp.sync.so/mcp

Führe dann /mcp in Claude Code aus, wähle sync und melde dich an. Füge --scope user hinzu, um es in jedem Projekt zu verwenden.

Codex

codex mcp add sync --url https://mcp.sync.so/mcp
codex mcp login sync

Cursor

Füge es in einem Projekt zu .cursor/mcp.json oder für alle Projekte zu ~/.cursor/mcp.json hinzu:

{
  "mcpServers": {
    "sync": { "url": "https://mcp.sync.so/mcp" }
  }
}

Cursor fordert dich bei der ersten Verbindung auf, dich bei sync. anzumelden.

VS Code

Füge es zu .vscode/mcp.json hinzu:

{
  "servers": {
    "sync": { "type": "http", "url": "https://mcp.sync.so/mcp" }
  }
}

Andere Clients

Jeder Client, der Remote-MCP-Server über Streamable HTTP mit OAuth unterstützt, kann https://mcp.sync.so/mcp verwenden. Der Client registriert sich selbst, und du meldest dich im Browser bei sync. an.

Der Server ist in der offiziellen MCP Registry als io.github.synchronicity-labs/mcp-server aufgeführt, sodass Clients und Verzeichnisse, die die Registry auslesen, ihn finden und hinzufügen können. server.json ist dieser Eintrag.

Lokaler Server mit einem API-Schlüssel

Für Clients ohne Remote-MCP-Unterstützung sowie für Skripte und CI kannst du den Server lokal über stdio mit einem sync.-API-Schlüssel ausführen:

claude mcp add sync -e SYNC_API_KEY=your-api-key -- npx -y @sync.so/mcp-server@latest

Oder in der JSON-Konfiguration eines Clients:

{
  "mcpServers": {
    "sync": {
      "command": "npx",
      "args": ["-y", "@sync.so/mcp-server@latest"],
      "env": { "SYNC_API_KEY": "your-api-key" }
    }
  }
}

Ohne SYNC_API_KEY startet der Server beim ersten Ausführen eine Geräteanmeldung: Rufe die ausgegebene URL auf und gib den Code ein. Das Token wird unter ~/.config/sync/mcp-credentials.json zwischengespeichert.

npm-Releases werden unabhängig von der gehosteten Bereitstellung veröffentlicht und können hinter dieser zurückliegen. Bevorzuge daher den gehosteten Server, wenn dein Client ihn unterstützt. @latest sorgt dafür, dass npx beim Neustart des Servers durch den Client die neueste Version abruft. Ohne diese Option kann npx weiterhin eine alte zwischengespeicherte Kopie ausführen.

Update-Hinweis

Beim Start fragt ein lokaler Server höchstens einmal täglich die npm-Registry nach der neuesten Version ab (die Antwort wird in ~/.config/sync/mcp-update-check.json zwischengespeichert). Die Prüfung läuft im Hintergrund mit einem Zeitlimit von zwei Sekunden und verzögert weder den Start noch einen Tool-Aufruf. Schlägt sie fehl, wird nichts angezeigt. Wenn eine neuere Version verfügbar ist, weisen die Anweisungen des Servers und das erste Tool-Ergebnis der Sitzung den Agenten an, dich zum Neustart mit npx -y @sync.so/mcp-server@latest oder zum Wechsel auf den gehosteten Server aufzufordern.

Um die Prüfung zu deaktivieren, setze SYNC_MCP_UPDATE_CHECK=off oder übergib --no-update-check. Sie wird auch übersprungen, wenn CI gesetzt ist. Der gehostete Server führt diese Prüfung nie aus.

Was du fragen kannst

Füge deinem Agenten Prompts wie diese ein. Asset-IDs findest du in deiner sync.-Bibliothek. Links können öffentliche Medien-URLs oder Videos von YouTube, TikTok, Instagram und Facebook sein.

Frage	Was der Agent tut
„Mache Video-Asset <video-asset-id> mit Audio-Asset <audio-asset-id> lippensynchron.“	lipsync_create mit den gespeicherten Assets und wartet dann auf das Ergebnis
„Mache https://example.com/talk.mp4 mit https://example.com/voiceover.wav. lippensynchron“	lipsync_create mit öffentlichen URLs
„Übersetze https://www.youtube.com/watch?v=… ins Spanische.“	Importiert den Link mit assets_create, nennt die Kosten und führt nach deiner Bestätigung dubbing_create aus
„Lass Video-Asset <video-asset-id> mit ruhiger Erzählerstimme ‚danke fürs Zuschauen‘ sagen.“	Wählt mit voices_list eine Stimme aus, nennt das Skript und führt dann lipsync_create mit script aus
„Wie viele Credits habe ich noch?“	account_get-usage
„Was hat meine letzte Generierung gekostet?“	Findet sie im Verlauf und liest generations_get-costs aus

Übersetzungen, Synchronisationen, Sprachvorschauen und Stimmklone werden dir vor dem Start mit Kostenvoranschlag zur Bestätigung vorgelegt.

Agent-Skills

Schrittweise Workflows für diese Tools (Lippensynchronisation, sprechende Fotos, Synchronisation, Edit Dialogue, Kampagnen, Stapelverarbeitung, Fehlerbehebung und die API) sind Agent-Skills in synchronicity-labs/skills. Installiere sie mit npx skills add synchronicity-labs/skills in jedem Agenten. Das ChatGPT- und Codex-Plugin enthält sie aus einem festgelegten Commit dieses Repositorys. Weitere Informationen findest du unter docs/chatgpt-plugin.md.

Tools

Der gehostete Server stellt jedem Client eine ausgewählte Gruppe von Tools bereit:

Bereich	Tools
Lippensynchronisation	lipsync_create, lipsync_create-timeline¹, generations_estimate-cost, generations_get, generations_list, generations_get-continuation, generations_get-costs, models_list
Übersetzung und Synchronisation	dubbing_create, dubbing_get-options, translation-previews_estimate, translation-previews_create, translation-previews_get
Sprache und Stimmen	speech-previews_create, speech-previews_get-options, speech-previews_get, voices_list, voices_clone
Edit Dialogue	dialogue_get-options, dialogue_upload-source, dialogue-transcriptions_create, dialogue-transcriptions_get, dialogue-previews_create, dialogue-previews_get, dialogue-videos_estimate, dialogue-videos_create
Assets	assets_create, assets_create-upload-url, assets_get, assets_list, assets_count, assets_get-download-url, assets_update, assets_delete, assets_get-playback-metadata, audio-trims_get, audio-trims_create
Projekte	projects_create, projects_get, projects_list, projects_list-generations, projects_rename
Viele Jobs	jobs_create-many², jobs_get-many²
Stapelverarbeitung	batches_create², batches_get², batches_list²
Konto	account_get-context, account_get-usage, organizations_list, organizations_select

¹ Wird in der ChatGPT-App nicht angeboten, da das eingebettete Studio keine Zeitleiste hat.

² Noch nicht in der ChatGPT-App-Auflistung enthalten. jobs_create-many startet bis zu 50 unabhängige Jobs gleichzeitig, etwa ein Video, das in mehrere Sprachen synchronisiert wird. Dazu wird ein Erstellungs-Tool (lipsync_create, dubbing_create, dialogue-videos_create und weitere) einmal pro Element ausgeführt, mit derselben API, denselben Limits und derselben Abrechnung wie bei einzelnen Aufrufen in jedem Tarif. jobs_get-many verfolgt den Fortschritt der Gruppe. Siehe Jobs. Eine Stapelverarbeitung ist eine separate, in die Warteschlange eingereihte Pipeline der API für umfangreiche Durchläufe (20 bis 500 Generierungen) in Scale-Tarifen und höher, die stundenlang warten können. Wenn der Tarif des Kontos keine Stapelverarbeitung umfasst, antwortet die API mit 402 und requiredPlan sowie billingUrl, die von den Tools weitergegeben werden.

Organisationen mit der entsprechenden Funktion erhalten außerdem scenes_detect (Kameraschnitte in einem Video) und stems_separate (Gesang und Hintergrund-Audio), außerhalb der ChatGPT-App. Lokal sind sie in den Toolsets lipsync und assets enthalten.

Clients mit App-Unterstützung erhalten außerdem die Tools hinter der eingebetteten Studio-App: Studio-Ansichten und -Entwürfe, das Upload-Widget und App-Hilfsfunktionen. Dazu gehören Clients, deren MCP-Handshake-Name das ChatGPT- oder Codex-App-Profil auswählt (openai-mcp, openai-mcp (Codex); siehe src/client-profile.ts). Andere Clients sehen diese Tools nicht, und ihre Aufrufe werden abgelehnt.

Lokale Toolsets

Der lokale stdio-Server kann auch für jeden anderen öffentlichen API-Vorgang in der OpenAPI-Spezifikation ein Tool bereitstellen, insgesamt über 65. Standardmäßig listet er die oben genannten gehosteten Tools ohne die Admin-Tools (assets_delete und voices_clone), sowie jobs_get, jobs_wait und die Tools transcriptions_*, deren Sprecher-Gesichtsspuren in lipsync_create-timeline-Clips einfließen.

Um weitere Tools aufzulisten, setze SYNC_MCP_TOOLSETS oder übergib --toolsets mit einer durch Kommas getrennten Liste:

Toolset	Fügt hinzu
default	Die oben genannten Standard-Tools; default,admin fügt also die Admin-Tools hinzu
lipsync	Lippensynchronisation, Zeitleiste, Edit Dialogue, Audio-Zuschnitt und Stapelverarbeitungs-Tools sowie die unverarbeiteten generate_*, generations_* und dialogue-edits_*
dubbing	Übersetzungs- und Synchronisations-Tools sowie die Stapelverarbeitungs-Tools
assets	assets_* (außer Löschvorgängen) und die Upload-Tools
projects	projects_* (außer Löschvorgängen) und projects_rename
transcription	transcriptions_*
voices	voices_* (außer Klonen und Löschvorgängen), Sprachvorschauen und tts_*
admin	Alle Löschvorgänge (assets_delete, projects_delete, generations_delete, voices_delete) und voices_clone
all	Jedes Tool, wie vor Einführung dieser Option

Job-, Konto- und Generierungsabfragen (jobs_get, jobs_wait, jobs_get-many, generations_get, account_get-context, organizations_list, organizations_select und ähnliche) sind in jeder Auswahl enthalten. Ebenso enthalten ist jobs_create-many, wenn ein von ihm ausgeführtes Erstellungs-Tool aufgelistet ist. Die Angabe von Toolsets ersetzt die Standardauswahl, statt sie zu ergänzen. Um wieder alle Tools zu erhalten:

claude mcp add sync -e SYNC_API_KEY=your-api-key -e SYNC_MCP_TOOLSETS=all -- npx -y @sync.so/mcp-server@latest

Wenn nicht alle Tools aufgelistet sind, erklären die Anweisungen des Servers dem Agenten, welche Toolsets aufgelistet sind und wie er die übrigen erhält, damit er dich auffordern kann, den Server mit einer größeren Auswahl neu zu starten. Der gehostete Server ignoriert diese Einstellung.

Tool-Workflows beschreibt das Verhalten der mehrstufigen und kostenpflichtigen Tools.

Tool-Namen folgen einem einheitlichen Schema <noun>_<verb> (lipsync_create, generations_get). Die zuvor verwendeten Namen (create-lipsync, generate_get-generation) funktionieren während einer Übergangsfrist weiterhin: Aufrufe über diese Namen führen dasselbe Tool aus und geben einen einzeiligen Hinweis mit dem neuen Namen aus. Unter Tool-Namen findest du die vollständige Tabelle „alt → neu“.

CLI-Optionen

Usage: sync-mcp [options]

Options:
  --api-key <key>     API key (or set SYNC_API_KEY env var)
  --base-url <url>    API base URL (default: https://api.sync.so)
  --transport <type>  stdio (default) or http
  --port <port>       HTTP port (default: 3002, only with --transport http)
  --no-spend-confirmation
                      Unattended automation: drop the cost-quote and confirm-before-paying
                      instructions (or set SYNC_MCP_SPEND_CONFIRMATION=off)
  --no-update-check   Skip the daily npm check for a newer version (or set
                      SYNC_MCP_UPDATE_CHECK=off; skipped when CI is set)
  --toolsets <list>   stdio only: comma-separated tools to list (or set SYNC_MCP_TOOLSETS):
                      default, lipsync, dubbing, assets, projects, transcription,
                      voices, admin or all (default: the hosted set without admin)
  -h, --help          Show this help message

Unbeaufsichtigte Automatisierung

Standardmäßig weisen die Tools den Agenten an, eine kostenpflichtige Aktion mit Kostenvoranschlag vorzulegen und auf die Genehmigung des Benutzers zu warten. Wenn der Server in einer Pipeline oder mit einem geplanten Agenten läuft, dessen Betreiber Ausgaben bereits genehmigt hat, starte ihn mit --no-spend-confirmation (oder SYNC_MCP_SPEND_CONFIRMATION=off). Der Agent erstellt dann Jobs, ohne einen Kostenvoranschlag vorzulegen oder nachzufragen, und Schätz-Tools bleiben verfügbar. Agenten können diese Einstellung nicht ändern.

Job-Tools akzeptieren wait: true, um auf dem Server zu warten (bis zu etwa 50 Sekunden pro Aufruf, mit Fortschrittsmeldungen, wenn der Client ein progressToken sendet): generations_get, translation-previews_get, transcriptions_get und Social-Media-Importe über assets_create. Auf dem lokalen Server erledigen jobs_wait und jobs_get dasselbe für jede Art von Job (Generierung, Transkription, Sprecheranalyse, Übersetzungsvorschau, Import) mit einer Eingabe, {kind, id, projectId?}, und einer einheitlichen Ergebnisstruktur und Statusmenge. Siehe Jobs. jobs_get-many liest auf beiden Servern auf diese Weise bis zu 50 Jobs gleichzeitig aus.

Wenn die API dies unterstützt, können Agenten mit feedback_send dem Sync-Team verwirrende Fehler, falsche Ergebnisse und fehlende Funktionen melden.

Umgebungsvariablen sowie die Limits für Sitzungen, Speicher, Uploads und Diagnosen des HTTP-Servers sind unter HTTP-Serverkonfiguration aufgeführt.

Funktionsweise

1. Beim Start ruft der Server die öffentliche OpenAPI-Spezifikation von {baseUrl}/api-json ab und wandelt jeden Vorgang in ein MCP-Tool mit einem Zod-Eingabeschema um.
2. Von Hand geschriebene Tools ergänzen mehrstufige Workflows auf derselben API, etwa Übersetzen und Synchronisieren, Edit Dialogue, Sprachvorschauen und Kostenabfragen.
3. Jeder Tool-Aufruf ist eine authentifizierte Anfrage an die sync.-API mit deinem OAuth- Token (gehostet) oder API-Schlüssel (lokal).

Über stdio wird ein neuer öffentlicher API-Vorgang beim nächsten Neustart zu einem Tool. Der gehostete Server stellt nur Tools auf seiner Zulassungsliste bereit. Ein neues gehostetes Tool wird daher mit einem Release dieses Repositorys veröffentlicht.

Programmatische Verwendung

Du kannst den Server auch als Bibliothek verwenden:

import { createSyncMcpServer, resolveConfig } from '@sync.so/mcp-server';

const config = resolveConfig({ apiKey: 'your-key' });
const server = await createSyncMcpServer(config);

Entwicklung

HTTPS-Quelltests verwenden den lokalen Befehl openssl, um eine selbstsignierte Testidentität mit einer Gültigkeit von einem Tag zu erstellen. Temporäre Zertifikats- und Schlüsseldateien werden vor dem Testlauf entfernt.

# Install dependencies
pnpm install

# Build
pnpm run build

# Run tests
pnpm test

# Lint
pnpm run lint

# Type check
pnpm run typecheck

# Script tests (monitor, smoke check, pre-commit size check)
pnpm run test:scripts

Für die Entwicklung wird Node 26 oder neuer benötigt (.nvmrc); devEngines in package.json erzwingt diese Version bei der Installation. pnpm install installiert einen Pre-Commit-Hook. Er führt Oxlint und Oxfmt für bereitgestellte Dateien aus und verhindert, dass eine bereitgestellte Quelldatei auf mehr als 5.000 Tokens (20.000 Bytes) anwächst. Dateien, die diese Größe bereits überschreiten, sind davon ausgenommen, bis sie aufgeteilt werden.

Lokales Testen des HTTP-Transports

So testest du den HTTP-Transport (OAuth-Ablauf) lokal:

1. Kopiere .env.example nach .env und trage die Werte ein
2. Starte einen Tunnel, um localhost freizugeben:

   ngrok http 3002
   

3. Aktualisiere MCP_ISSUER_URL in .env mit der ngrok-URL
4. Starte den Server:

   source .env
   node dist/cli.js --transport http --base-url $SYNC_BASE_URL --port 3002
   

5. Überprüfe, ob es funktioniert:

   curl https://<ngrok-url>/health
   curl https://<ngrok-url>/.well-known/oauth-authorization-server
   

Wenn für eine isolierte Studio-Anmeldung der Webproxy mit demselben Ursprung erforderlich ist, setze SYNC_OAUTH_AUTHORIZATION_URL auf dessen /api-proxy/v2/oauth/authorize-URL und belasse SYNC_BASE_URL beim direkten isolierten API-Listener. Nur die Browsernavigation verwendet den Webproxy. Registrierung, Codeaustausch, Aktualisierung, Widerruf, userinfo und Tool-Aufrufe verwenden die direkte API und behalten die bestehenden Fristen, PKCE- und Confidential-Client-Prüfungen bei. Die optionale URL muss HTTP(S) verwenden und darf keine Zugangsdaten, Abfrageparameter oder Fragmente enthalten. Bestehende Deployments benötigen keine neue Einstellung.

6. Füge https://<ngrok-url>/mcp als benutzerdefinierten Connector in Claude Web hinzu

Weitere Informationen

• Tool-Workflows — Funktionsweise mehrstufiger und kostenpflichtiger Tools
• HTTP-Serverkonfiguration — Umgebungsvariablen und Laufzeitlimits
• Hinweise für Maintainer — Kompatibilität mit gehosteten Umgebungen, Abbruch, OAuth-Proxy, Uploads und Monitoring
• Bereitschaft für das Claude-Verzeichnis — Prüfliste und noch ausstehende Einreichungsarbeiten
• Sync-Dokumentation — Vollständige API-Referenz und Anleitungen
• Sync-API-Referenz — Endpunktdokumentation
• MCP-Protokoll — Erfahre mehr über das Model Context Protocol
• Sync-Website — Registriere dich und leg los

Lizenz

MIT