BrewForge Docs

MCP-Server

Verbinde BrewForge mit Claude, ChatGPT, Cursor, VS Code und anderen KI-Assistenten über den BrewForge-MCP-Server: Einrichtung, Anmeldung per OAuth oder API-Token, Toolsets, Sicherheit und Fehlersuche.

BrewForge betreibt einen MCP-Server. Füge ihn einem KI-Assistenten hinzu, und der Assistent arbeitet mit deinen Braudaten so wie du in der App: einen Sud nachschlagen, den nächsten Sud planen, eine Extraktmessung eintragen, nachsehen, was gerade gezapft wird, oder herausfinden, welche Zutaten dir fehlen.

https://brewforge.sh/api/mcp

Jedes Tool des MCP-Servers ist auch eine Action der Actions-API, mit demselben Namen, denselben Parametern und Ergebnissen. Die Tool-Referenz listet alle auf.

Pro-Tarif

MCP-Server und API brauchen mindestens den Pro-Tarif. Verbinden kannst du einen Assistenten in jedem Tarif, aber jeder Tool-Aufruf antwortet mit TIER_REQUIRED, bis dein Konto Pro hat.

Was ein Assistent kann

Alles, was du in der App mit deinen eigenen Braudaten machst: Rezepte und Sude von der Idee bis zur Abfüllung, Brautag-Messungen, Gärmessungen, Bewertungen, Geräte, den Keller, abgefüllten Vorrat, Taplisten und Etiketten, deinen Zutatenbestand, Bestellungen und den Planer, Profile und Bierstile, eigene Felder, Einstellungen, den Kalender, Rechner, Importe und Exporte, die Community, Feedback und Support-Tickets.

Was er nicht kann: Passwort, E-Mail, Sitzungen oder API-Token ändern, dein Konto löschen, Zahlungsdaten oder deinen Tarif sehen oder ändern oder Admin-Funktionen nutzen. Das steht auch auf der Zustimmungsseite.

Assistenten verbinden

Es gibt zwei Arten der Anmeldung:

  • Anmeldung per OAuth (empfohlen): Du gibst die URL ein, der Assistent öffnet BrewForge im Browser, du meldest dich an und klickst auf Erlauben. Kein Token zum Kopieren, und unter Einstellungen → Integrationen → API-Token → Verbundene Apps kannst du die App jederzeit trennen.
  • API-Token: für Clients ohne OAuth oder für Skripte. Erstelle ein Token unter Einstellungen → Integrationen → API-Token und schick es als Header Authorization: Bearer bfk_… mit.

In claude.ai oder der Claude-Desktop-App:

  1. Öffne Settings → Connectors und klicke auf Add custom connector.
  2. Nenne ihn „BrewForge“ und gib die URL https://brewforge.sh/api/mcp ein.
  3. Klicke auf Connect. BrewForge öffnet sich: Melde dich an, falls nötig, prüfe, was die App darf, und klicke auf Erlauben.

Schalte den Connector im Chat im Tools-Menü ein und leg los.

Mit OAuth:

claude mcp add --transport http brewforge https://brewforge.sh/api/mcp

Führe dann in einer Claude-Code-Sitzung /mcp aus, wähle brewforge und Authenticate. Dein Browser öffnet BrewForge; melde dich an und klicke auf Erlauben.

Stattdessen mit API-Token:

claude mcp add --transport http brewforge https://brewforge.sh/api/mcp \
  --header "Authorization: Bearer bfk_dein_token"

Wenn dein ChatGPT-Tarif eigene Connectors (MCP-Server) erlaubt, leg einen mit der URL https://brewforge.sh/api/mcp und OAuth als Anmeldung an. ChatGPT öffnet BrewForge zur Anmeldung; klicke auf Erlauben.

Trag den Server in ~/.cursor/mcp.json (alle Projekte) oder .cursor/mcp.json (ein Projekt) ein:

{
  "mcpServers": {
    "brewforge": { "url": "https://brewforge.sh/api/mcp" }
  }
}

Beim ersten Mal bittet Cursor dich, dich bei BrewForge anzumelden. Für ein API-Token ergänze "headers": { "Authorization": "Bearer bfk_dein_token" } neben url.

Trag den Server in .vscode/mcp.json deines Projekts ein (oder nutze MCP: Add Server in der Befehlspalette):

{
  "servers": {
    "brewforge": { "type": "http", "url": "https://brewforge.sh/api/mcp" }
  }
}

Beim Start des Servers öffnet VS Code BrewForge zur Anmeldung. Für ein API-Token ergänze "headers": { "Authorization": "Bearer bfk_dein_token" }.

Jeder MCP-Client mit Streamable HTTP funktioniert. Der Server ist zustandslos: Jede Anfrage ist ein POST mit einer JSON-RPC-Nachricht und wird mit JSON beantwortet (keine Sitzungen, kein Event-Stream).

  • OAuth 2.1 mit Discovery: Der Client bekommt eine 401 mit einem WWW-Authenticate-Header, der auf https://brewforge.sh/.well-known/oauth-protected-resource/api/mcp zeigt, registriert sich selbst (Dynamic Client Registration) und meldet dich mit PKCE an.
  • Oder schick ein API-Token als Authorization: Bearer bfk_….

Anmeldung per OAuth im Detail

  • Die App fragt nach read (deine Daten sehen) oder write (sehen und ändern). Die Zustimmungsseite auf brewforge.sh zeigt den Namen der App, was sie dann darf und wohin es danach zurückgeht.
  • Zugriffstoken gelten eine Stunde; die App erneuert sie mit einem Refresh-Token, das 30 Tage gilt und sich bei jeder Nutzung ändert. Solange du die App mindestens einmal im Monat nutzt, bleibst du verbunden.
  • Einstellungen → Integrationen → API-Token listet unter Verbundene Apps, wann eine App verbunden wurde und zuletzt aktiv war und ob sie Nur lesen oder Lesen und ändern darf. Klick eine an und dann Trennen, um ihr sofort den Zugriff zu entziehen.
  • OAuth-Verbindungen bekommen immer Zugriff auf alle Bereiche. Willst du einen Assistenten auf einzelne Bereiche beschränken (nur Sude, nur Bestand, …), nimm ein API-Token mit Bereichs-Berechtigungen.

Tools auswählen

Standardmäßig bietet der Server alle Tools an (mehr als 100). Assistenten arbeiten mit weniger besser, deshalb kannst du sie über die URL eingrenzen:

URLTools
https://brewforge.sh/api/mcpAlle Toolsets
https://brewforge.sh/api/mcp?toolsets=brewing,cellarNur diese Toolsets (plus core)
https://brewforge.sh/api/mcp?read_only=1Nur lesende Tools; nichts kann geändert werden
https://brewforge.sh/api/mcp?toolsets=inventory&read_only=1Beides kombiniert

Die Toolsets:

ToolsetUmfasst
coreget_started: Konto, Tarif, Einheiten, freigeschaltete Funktionen und eine Übersicht der anderen Tools. Immer dabei.
brewingRezepte und Sude, Brautag, Gärmessungen, Bewertungen und Geräte
cellarKellerbehälter, Abfüllung, abgefüllter Vorrat, Taplisten und Etiketten
inventoryZutatenbestand, Zutatenkatalog, Pakete, Bestellungen und der Planer
setupProfile, Bierstile, eigene Felder, Einstellungen, Kalender, Auswertung, Rechner, Importe und Exporte
communityCommunity, Rezepte teilen, Feedback, Support-Tickets, Posteingang und Changelog

Ein API-Token blendet außerdem die Tools aus, die seine Berechtigungen nicht erlauben: Ein Token mit nur brews:read sieht nur die Tools, die Sude lesen.

Beispiel-Prompts

Sicherheit

  • Löschen braucht eine Bestätigung. Tools, die etwas löschen oder rückgängig machen (in der Tool-Referenz als löschend markiert), ändern beim ersten Aufruf nichts. Sie liefern, was entfernt würde, und erst ein zweiter Aufruf mit confirm: true führt es aus. Assistenten sind angewiesen, dir diese Vorschau zu zeigen und vor dem Bestätigen zu fragen.
  • Öffentliche Beiträge. Feedback-Beiträge, Antworten, Support-Tickets und Community-Aktionen sehen andere Menschen oder das BrewForge-Team. Lass dir den Text vom Assistenten zeigen und bestätige ihn, bevor er gepostet wird.
  • Erst nur lesen. Zum Ausprobieren verbinde mit ?read_only=1 oder gib dem API-Token nur Lese-Berechtigungen.
  • Trenne Apps, die du nicht mehr nutzt, unter Verbundene Apps, und lösche API-Token, die du nicht mehr brauchst.

Limits

Tool-Aufrufe teilen sich ein Rate-Limit mit der Actions-API: 600 Anfragen pro Stunde und 20.000 pro 30 Tage pro Konto. Jede Anfrage an den MCP-Server zählt, auch wenn der Client die Tools abfragt. Siehe Rate-Limits.

Fehlersuche

Was du siehstWarumWas hilft
401 / UNAUTHORIZED, oder der Client will sich neu anmeldenKein Token, ein unbekanntes oder gelöschtes API-Token, oder die OAuth-Verbindung wurde getrennt oder ist abgelaufenIm Client neu anmelden (in Claude Code: /mcp → Authenticate) oder das API-Token prüfen
TIER_REQUIREDDein Konto hat nicht mindestens Pro, oder ein Tool braucht eine Funktion, die dein Tarif nicht enthältTarif wechseln; die Meldung nennt den nötigen Tarif
SCOPE_REQUIREDDem API-Token fehlt die Berechtigung für dieses ToolBerechtigung unter Einstellungen → Integrationen → API-Token ergänzen; das Token selbst bleibt gleich
FORBIDDEN … „not enabled on this MCP connection“Das Toolset des Tools fehlt in ?toolsets=, oder die Verbindung ist ?read_only=1URL im Client ändern
RATE_LIMITEDMehr als 600 Anfragen in einer Stunde (oder 20.000 in 30 Tagen)So viele Sekunden warten, wie die Meldung nennt
NOT_FOUND / AMBIGUOUS_REFERENCE mit KandidatenEin Sud, Rezept oder etwas anderes wurde nicht gefunden oder passt mehrfachAssistenten versuchen es selbst mit einer der genannten IDs; sonst sag, welches du meinst

Alle Fehler und ihre Bedeutung: Actions-API → Fehler.

Auf dieser Seite