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/mcpJedes 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:
- Öffne Settings → Connectors und klicke auf Add custom connector.
- Nenne ihn „BrewForge“ und gib die URL
https://brewforge.sh/api/mcpein. - 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/mcpFü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
401mit einemWWW-Authenticate-Header, der aufhttps://brewforge.sh/.well-known/oauth-protected-resource/api/mcpzeigt, 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:
| URL | Tools |
|---|---|
https://brewforge.sh/api/mcp | Alle Toolsets |
https://brewforge.sh/api/mcp?toolsets=brewing,cellar | Nur diese Toolsets (plus core) |
https://brewforge.sh/api/mcp?read_only=1 | Nur lesende Tools; nichts kann geändert werden |
https://brewforge.sh/api/mcp?toolsets=inventory&read_only=1 | Beides kombiniert |
Die Toolsets:
| Toolset | Umfasst |
|---|---|
core | get_started: Konto, Tarif, Einheiten, freigeschaltete Funktionen und eine Übersicht der anderen Tools. Immer dabei. |
brewing | Rezepte und Sude, Brautag, Gärmessungen, Bewertungen und Geräte |
cellar | Kellerbehälter, Abfüllung, abgefüllter Vorrat, Taplisten und Etiketten |
inventory | Zutatenbestand, Zutatenkatalog, Pakete, Bestellungen und der Planer |
setup | Profile, Bierstile, eigene Felder, Einstellungen, Kalender, Auswertung, Rechner, Importe und Exporte |
community | Community, 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: truefü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=1oder 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 siehst | Warum | Was hilft |
|---|---|---|
401 / UNAUTHORIZED, oder der Client will sich neu anmelden | Kein Token, ein unbekanntes oder gelöschtes API-Token, oder die OAuth-Verbindung wurde getrennt oder ist abgelaufen | Im Client neu anmelden (in Claude Code: /mcp → Authenticate) oder das API-Token prüfen |
TIER_REQUIRED | Dein Konto hat nicht mindestens Pro, oder ein Tool braucht eine Funktion, die dein Tarif nicht enthält | Tarif wechseln; die Meldung nennt den nötigen Tarif |
SCOPE_REQUIRED | Dem API-Token fehlt die Berechtigung für dieses Tool | Berechtigung 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=1 | URL im Client ändern |
RATE_LIMITED | Mehr 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 Kandidaten | Ein Sud, Rezept oder etwas anderes wurde nicht gefunden oder passt mehrfach | Assistenten versuchen es selbst mit einer der genannten IDs; sonst sag, welches du meinst |
Alle Fehler und ihre Bedeutung: Actions-API → Fehler.
API-Überblick
Die APIs von BrewForge: REST-API, Actions-API und MCP-Server für KI-Assistenten, um Sude, Bestand, Profile und mehr aus Skripten und anderen Apps zu lesen und zu ändern
Actions-APIPro
Die Actions-API von BrewForge: aufgabenbezogene Actions wie log_fermentation_reading oder package_beer per HTTP, mit Übersicht, Verweisen per Name, kanonischen Einheiten, Bestätigung beim Löschen und Fehlern, die erklären, was zu tun ist.