MCP-Server (Claude und KI-Assistenten)

Eine sichere Brücke zwischen Ihren Kellerdaten und einem MCP-fähigen Client. Nach der Authentifizierung kann der Assistent VinoCellar-Tools in Ihrem Namen aufrufen — gemäß Abo und Kontoregeln.

Die genaue öffentliche URL steht in der VinoCellar-App auf dem MCP-/Token-Bildschirm (interne Route /app/mcp), Abschnitt «MCP-Server-Adresse». Kopieren Sie sie unverändert.

In der öffentlichen VinoCellar-Produktions-App ist der Standard-MCP-Host https://mcp.vinocellar.app . Bevorzugen Sie stets den in der App angezeigten Wert, falls er abweicht (eigene Builds oder künftige Konfiguration über EXPO_PUBLIC_MCP_SERVER_URL).

1. App öffnen → Bereich MCP (oder Einstellungen → VinoCellar MCP → Token verwalten).
2. Server-URL aus dem vorgesehenen Block kopieren.
3. In Claude Desktop (oder anderem Client) MCP-Server hinzufügen und URL laut aktueller Client-Dokumentation einfügen.
4. Beim ersten Verbinden den OAuth-Schritt im Browser abschließen; persönliches Token aus der App einfügen, wenn das Formular es verlangt.

Der VinoCellar-MCP-Server folgt der MCP-Spezifikation mit Streamable HTTP: Ihr Client spricht den MCP-Endpunkt per HTTPS an (kein generischer REST-Katalog zum manuellen Durchstöbern).

Beim ersten Verbindungsaufbau startet der MCP-Client einen OAuth-ähnlichen Ablauf. Im Browser fügen Sie das persönliche Zugriffstoken ein, das Sie in der VinoCellar-App erstellt haben; der MCP-Server prüft es gegen die VinoCellar-API und stellt dann Anmeldedaten aus, die Ihr Client bei weiteren MCP-Anfragen als Bearer-Token sendet.

Über den MCP-Bildschirm erstellte Tokens erhalten die Bereiche mcp:read und mcp:write, damit der Assistent die von VinoCellar registrierten Tools nutzen kann.

Zur einfachen Erreichbarkeit des Hosts (ohne vollständige MCP-Sitzung) antwortet der Server auf GET /ping mit dem Klartext pong.

Das Token identifiziert Ihr Konto gegenüber dem MCP-Server:

1. In der App MCP-Bildschirm öffnen und Token erstellen.
2. Klare Bezeichnung vergeben (z. B. «MacBook», « Claude Desktop », «Cursor»).
3. Wert sofort kopieren — er wird nur einmal angezeigt.
4. Token auf demselben Bildschirm widerrufen, wenn ein Gerät verloren geht oder ein Client getrennt werden soll.

Tokens wie Passwerte behandeln: Wer Token und URL hat, kann bis zur Widerruf über MCP auf Ihren Keller zugreifen.

Dies sind die exakten Tool-Bezeichner, die MCP-Clients sehen:

• vinocellar_whoami — Verbindung prüfen; die JSON-Antwort enthält ein mcp-Objekt (Willkommenstext, FAQ-URL, Tool-Hinweise).
• vinocellar_help — dasselbe Onboarding-JSON wie das mcp-Objekt von vinocellar_whoami, ohne erneuten Profil-API-Aufruf.
• vinocellar_list_wines — breite Inventarliste; vinocellar_search_wines bevorzugen, wenn nach Name oder Domäne gefiltert wird.
• vinocellar_search_wines — Volltextsuche über Ihre Flaschen.
• vinocellar_get_caves — Keller auflisten, bevor einer gewählt wird.
• vinocellar_get_cave — Kellerlayout mit Fächern; liefert log_id für vinocellar_move_bottle.
• vinocellar_move_bottle — Flasche per log_id aus vinocellar_get_cave in ein anderes Fach oder einen anderen Keller verschieben.
• vinocellar_import_wine — Wein aus strukturiertem wine_data (Form GeminiWineResponse) hinzufügen, optional Vorder-/Rücketikett als Base64; erfordert ein aktives MCP-Abo auf dem Konto.

Die MCP-Tools beschränken sich auf die oben genannten Keller- und Bestandsvorgänge.

Der Vino-Chat in der App, der Speisen-Wein-Assistent, das Verkostungstagebuch und ähnliche KI-Funktionen sind keine separaten MCP-Tools — nutzen Sie dafür die mobile oder Web-App.

VinoCellar richtet sich an Nutzerinnen und Nutzer mit einem kompatiblen MCP-Client (z. B. Claude Desktop): Server-URL aus der App kopieren und persönliches Token erstellen.

Es gibt keine separate Partner-OAuth-App und kein OpenAPI-Dokument «MCP als REST»: Vertrag ist das MCP-Protokoll (tools/list sowie Beschreibung/Schema jedes Tools, wie Ihr Client sie anzeigt).

Credits werden vor allem für Etikettenscans in der App genutzt. Das MCP-Abo ist getrennt: Solange es aktiv ist, sind Aufrufe über den MCP-Server für unterstützte Vorgänge nicht in gleicher Weise durch Ihr Scan-Credit-Guthaben begrenzt.

Heute Claude Desktop und MCP-fähige Clients mit VinoCellar-Transport. ChatGPT- und Gemini-Kompatibilität ist geplant; siehe Release Notes und diese FAQ.