fatsecret-mcp

Ein persönlicher Remote-MCP-Server (Model Context Protocol), der es Claude ermöglicht, die Lebensmittel- und Rezeptdatenbank von FatSecret zu durchsuchen und dein eigenes Ernährungstagebuch, Gewicht und Trainingsprotokoll direkt im Gespräch zu lesen und zu schreiben. Bereitgestellt auf Vercels kostenlosem Hobby-Tarif. Schwesterprojekt zu fitness-mcp (Hevy) — ein MCP-Server pro Produkt, die dasselbe Authentifizierungsmuster nutzen.

Lizenz

MIT

Status

• Suche (Phase 2): implementiert — search_foods, get_food_detail, search_recipes, get_recipe_detail, find_food_by_barcode. Keine FatSecret-Benutzerautorisierung erforderlich; nur die OAuth-2.0-Client-ID und das Client-Secret aus der FatSecret-Entwicklerkonsole.

• Tagebuch/Gewicht/Training/Profil (Phase 4): implementiert, aber nicht gegen ein echtes FatSecret-Konto verifiziert — es gab keine FatSecret-API-Registrierung, als dies gebaut wurde (siehe „Was nicht verifiziert ist“ unten). Bestätige die genauen Feldnamen jeder Methode anhand eines echten Kontos, bevor du dich darauf verlässt, und aktualisiere Code/Tests, falls etwas nicht stimmt.

• 3-legged-OAuth1-Setupskript (Phase 3): implementiert (scripts/fatsecret-oauth-setup.ts), aber noch nicht gegen ein echtes FatSecret-Konto ausgeführt.

Zwei Authentifizierungsebenen

Dieser Server sitzt zwischen Claude und FatSecret, und diese beiden Beziehungen werden jeweils völlig unterschiedlich authentifiziert — das ist das Wichtigste, was man verstehen sollte, bevor man den Code anfasst.

Claude  <──①── this server (fatsecret-mcp)  ──②──>  FatSecret API

① Claude ↔ dieser Server — ein einziges gemeinsames Geheimnis, gleiches Muster wie fitness-mcp. Claude sendet bei jeder Anfrage Authorization: Bearer <MCP_BEARER_TOKEN>; lib/auth.ts prüft es. Da Claudes Static-Header-Option weiterhin per Beta beschränkt ist, betreibt dieser Server auch einen eigenen minimalen OAuth-2.1-Autorisierungsserver (lib/oauth.ts, /api/oauth/authorize, /api/oauth/token), sodass die standardmäßigen OAuth-Client-ID/Secret-Felder von Claude als immer verfügbare Fallback-Option funktionieren — siehe README von fitness-mcp für die vollständige Begründung, die hier unverändert gilt.

② dieser Server ↔ FatSecret — hier wird es komplexer als bei fitness-mcp, weil FatSecret selbst zwei verschiedene OAuth-Versionen für zwei verschiedene Arten von API-Methoden verwendet, und daran führt kein Weg vorbei — so ist die FatSecret-API entworfen, keine Entscheidung, die hier getroffen wurde:

Konkret: search_foods/get_food_detail/search_recipes/get_recipe_detail/find_food_by_barcode funktionieren, sobald du eine FatSecret-App registriert und FATSECRET_CLIENT_ID/FATSECRET_CLIENT_SECRET gesetzt hast. Alle anderen Tools benötigen zusätzlich FATSECRET_CONSUMER_KEY/FATSECRET_CONSUMER_SECRET (OAuth1 — ein anderes Anmeldedatenpaar aus derselben FatSecret-App) sowie FATSECRET_ACCESS_TOKEN/FATSECRET_ACCESS_TOKEN_SECRET (erhalten durch einmaliges Ausführen des Setupskripts).

Verfügbare Tools

Schreib-Tools sind standardmäßig Dry-Runs

Gleiches Design wie fitness-mcp: Jedes Schreib-Tool erfordert ein Argument confirm: true. Ihre Beschreibungen weisen das aufrufende LLM an, dem Benutzer genau zu zeigen, was geschrieben wird, und zuerst eine ausdrückliche Zustimmung einzuholen. Das ist ein struktureller Anstoß, keine Garantie — dasselbe LLM, das entscheidet, ob das Tool aufgerufen wird, setzt auch confirm, und es gibt keine Trennung der Berechtigungen zwischen Lese-/Schreib-Tools auf der Authentifizierungsebene, sodass jeder Aufrufer mit einem gültigen MCP_BEARER_TOKEN jedes Tool aufrufen kann.

Was nicht verifiziert ist

Es gab keine FatSecret-API-Registrierung, als dieses Projekt gebaut wurde (dieser Schritt erfordert einen Menschen — siehe Einrichtung unten), daher:

• Die Methodennamen und Kernparameter von search_foods/get_food_detail/search_recipes/get_recipe_detail/profile.get/food_entries.get/weights.get_month sind gegen funktionierende Drittanbieter-Implementierungen von FatSecret-Clients bestätigt (nicht geraten) — siehe die Git-Historie für Quellen.

• Die Antwortstruktur von food.find_id_for_barcode, die Parameternamen von weight.update und alle exercise_entries.* sind Best-Effort-Rekonstruktionen, die inline in lib/fatsecret/*.ts mit der Begründung gekennzeichnet sind. Behandle sie als soliden Ausgangspunkt, nicht als verifizierte Wahrheit.

• Führe die manuelle Verifikations-Checkliste unten nach der Registrierung gegen ein echtes Konto aus und korrigiere alle Feldnamen-Abweichungen, die du findest (die Unit-Tests in lib/fatsecret/*.test.ts müssen entsprechend aktualisiert werden).

Einrichtung

1. Registriere eine FatSecret-Platform-API-App unter https://platform.fatsecret.com/. Du erhältst:

   • Eine OAuth-2.0-Client-ID/Secret (für FATSECRET_CLIENT_ID/FATSECRET_CLIENT_SECRET).

   • Einen OAuth-1.0-Consumer-Key/Secret (für FATSECRET_CONSUMER_KEY/FATSECRET_CONSUMER_SECRET) — ein separates Paar aus derselben App, nicht identisch mit den OAuth2-Anmeldedaten oben.

   • Prüfe, welche Scopes dein Tarif enthält (basic / premier / barcode / ...) — weights.get_month/weight.update/find_food_by_barcode sollen Premier bzw. die Scopes barcode/premier erfordern; bestätige das für deinen eigenen Tarif und passe FATSECRET_OAUTH2_SCOPE bei Bedarf an.

   • Nimm deine ausgehenden IP-Adressen in die Allowlist auf für OAuth2-Tokenanfragen — FatSecret verlangt das (bis zu 15 Adressen/Bereiche). Wenn du auf Vercel bereitstellst, benötigst du eine statische ausgehende IP (z. B. über einen von Vercel unterstützten Egress-Proxy/Add-on); die standardmäßigen serverlosen Funktionen von Vercel haben keine feste IP.

2. Führe den lokalen Entwicklungsserver einmal aus, um die Suche zu testen (Phase 2 benötigt nur Schritt 1): GXP2

3. Führe das einmalige 3-legged-OAuth1-Setup aus (erforderlich für jedes Tool außer den 5 Such-/Detail-Tools) — siehe Phase 3 unten.

4. Stelle auf Vercel bereit — siehe Bereitstellung unten.

Lokale Entwicklung

npm install
cp .env.example .env.local   # fill in real values
vercel dev

Smoke-Test (ersetze $MCP_BEARER_TOKEN):

curl -X POST http://localhost:3000/api/mcp \
  -H "Authorization: Bearer $MCP_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Sollte die 17 Tools oben zurückgeben. Eine Anfrage mit fehlendem/falschem Token sollte 401 erhalten.

Phase 3: Einmaliges 3-legged-OAuth1-Setup

Jedes Tool außer search_foods/get_food_detail/search_recipes/get_recipe_detail/find_food_by_barcode benötigt ein OAuth1-Access-Token/Secret, das an dein FatSecret-Konto gebunden ist. Du erhältst es einmalig:

npm run fatsecret:oauth-setup

Dieses Skript (scripts/fatsecret-oauth-setup.ts) wird:

1. Ein nicht autorisiertes Request-Token von FatSecret anfordern.

2. Eine Autorisierungs-URL ausgeben — öffne sie, melde dich bei FatSecret an und genehmige. FatSecret zeigt einen Bestätigungscode.

3. Dich auffordern, diesen Code einzufügen, und ihn dann gegen ein dauerhaftes Access-Token/Secret eintauschen.

4. FATSECRET_ACCESS_TOKEN/FATSECRET_ACCESS_TOKEN_SECRET in .env.local schreiben.

Füge dann dieselben beiden Werte auch zu den Umgebungsvariablen von Vercel hinzu (.env.local wird niemals bereitgestellt) — siehe Bereitstellung unten.

Laut der FatSecret-Dokumentation läuft dieses Access Token nicht ab. Falls es jemals widerrufen wird (z. B. wenn du den App-Zugriff in deinen FatSecret-Kontoeinstellungen entfernst), führe einfach das Skript erneut aus, um ein neues zu erhalten — im Geiste des derive()-Musters von fitness-mcp: Verlorene Zugangsdaten sind hier keine Katastrophe, sondern mit einem einzigen Befehl behoben — nur diesmal interaktiv statt durch eine deterministische Neuableitung.

Generieren der Claude-zugewandten Geheimnisse aus einer einprägsamen Passphrase

MCP_BEARER_TOKEN, OAUTH_CLIENT_ID und OAUTH_CLIENT_SECRET (Ebene ① — Claude ↔ dieser Server, unabhängig von den FatSecret-Zugangsdaten oben) können alle deterministisch aus einer einzigen Master-Passphrase abgeleitet werden. Ein Verlust der gespeicherten Werte ist also keine Katastrophe — leite sie einfach neu ab:

derive() {
  if [ -z "$MASTER_PASSPHRASE" ]; then
    printf "Master passphrase: "
    read -rs MASTER_PASSPHRASE
    echo
  fi
  echo -n "$1" | openssl dgst -sha256 -hmac "$MASTER_PASSPHRASE" -hex | awk '{print $2}'
}

derive "fatsecret-mcp:bearer-token"        # → MCP_BEARER_TOKEN
derive "fatsecret-mcp:oauth-client-id"     # → OAUTH_CLIENT_ID
derive "fatsecret-mcp:oauth-client-secret" # → OAUTH_CLIENT_SECRET

Die Label-Strings sind nicht geheim (sie können bedenkenlos in dieser README bleiben) — nur die Passphrase ist es. Wenn derive erneut mit derselben Passphrase ausgeführt wird, reproduziert es immer dieselben Werte. Dies gilt nicht für die FatSecret-seitigen Zugangsdaten (FATSECRET_CLIENT_ID/SECRET, FATSECRET_CONSUMER_KEY/SECRET, FATSECRET_ACCESS_TOKEN/SECRET) — diese stammen aus der FatSecret-Entwicklerkonsole und dem OAuth1-Einrichtungsskript, nicht aus dieser Passphrase.

Testen

Drei Ebenen, die bei jedem Push/PR in CI (.github/workflows/ci.yml) laufen — keine benötigt echte FatSecret-Geheimnisse, daher funktionieren sie in einem öffentlichen Repository genauso:

npm run test        # unit + integration (vitest) — pure logic, plus the real Next.js
                     # route handler exercised with fetch mocked
npm run build
npm run test:e2e     # starts a real `next start` server and hits it over real HTTP
                      # (node's built-in test runner, no extra dependency)

• Unit (lib/**/*.test.ts): Bearer-Token-Verifizierung, OAuth2.1-Code-Signierung/PKCE/Redirect-URI-Allowlisting (RFC-7636-Testvektor enthalten), FatSecret-OAuth2-Client-Credentials-Token-Abruf/Cache/Refresh (lib/fatsecret/appAuth.test.ts), OAuth1-HMAC-SHA1-Signierung, die gegen eine unabhängige Neuimplementierung geprüft wurde (lib/fatsecret/oauth1.test.ts), und die Antwortform-Normalisierung jeder lib/fatsecret/*.ts-Datei (Einzelobjekt-vs-Array, Zahlenstring-vs-Zahl, Leerantwort-Eigenheiten).

• Integration (test/integration/*.test.ts): Der echte app/api/mcp/route.ts-Handler, verbunden mit den echten lib/fatsecret/*-Modulen, wobei nur fetch gemockt ist. Abgedeckt werden sowohl die OAuth2-Pfade (Signed Request) als auch die OAuth1-Pfade (Signed & Delegated) der Tools sowie die Bestätigungsabsicherung (confirm-gating) bei jedem Schreib-Tool; die echten Routen /api/oauth/authorize//api/oauth/token; die OAuth-Metadatenrouten unter .well-known.

• E2E (test/e2e/*.e2e.test.mjs): Startet den Produktions-Build und prüft über echtes HTTP — Health Check, 401 bei fehlender/falscher Authentifizierung, tools/list liefert alle 17 Tools, OAuth-Discovery-Metadaten und einen vollständigen Authorization-Code- + PKCE-Roundtrip. Es werden keine echten FatSecret-Daten verwendet (CI hat bewusst keine echten Zugangsdaten).

Manuelle Überprüfung mit einem echten FatSecret-Konto

CI greift nie auf echte FatSecret-Daten zu, und — wie oben unter „Was ist unverifiziert“ erwähnt — wurden einige Annahmen dieses Servers über die exakten Antwortstrukturen von FatSecret noch nie mit einem echten Konto überprüft. Nach der Registrierung und dem Ausführen des OAuth1-Einrichtungsskripts arbeitest du diese Checkliste durch und behebst alle gefundenen Abweichungen:

1. Setze echte FATSECRET_CLIENT_ID/FATSECRET_CLIENT_SECRET in .env.local, führe vercel dev aus und rufe search_foods mit einer echten Abfrage auf (z. B. über das Smoke-Test-curl-Muster oben mit tools/call) — bestätige, dass echte Ergebnisse zurückkommen und get_food_detail für eines davon plausible Nährwerte liefert.

2. Rufe search_recipes und get_recipe_detail entsprechend auf.

3. Falls dein Plan den barcode-Scope umfasst, rufe find_food_by_barcode mit dem Barcode eines echten Produkts auf und bestätige, dass die Antwortstruktur mit RawFindIdForBarcodeResponse aus lib/fatsecret/foods.ts übereinstimmt — korrigiere sie andernfalls.

4. Führe npm run fatsecret:oauth-setup aus und rufe dann get_profile und get_food_diary auf — bestätige, dass die Feldnamen in lib/fatsecret/profile.ts/lib/fatsecret/diary.ts mit der echten Antwort übereinstimmen (sie wurden aus Dokumentationen rekonstruiert, nicht aufgezeichnet).

5. Rufe create_food_diary_entry mit confirm: true und einem offensichtlichen Wegwerf-Eintrag auf, danach get_food_diary für dasselbe Datum und bestätige, dass der Eintrag mit den richtigen Werten für Lebensmittel/Portion/Menge/Mahlzeit erscheint. Anschließend update_food_diary_entry und delete_food_diary_entry — bestätige, dass beide Vorgänge vollständig durchlaufen.

6. Falls dein Plan Gewichtstracking umfasst, rufe update_weight mit confirm: true auf und bestätige, dass get_weight_history dies widerspiegelt.

7. create_exercise_entry und get_exercise_diary sind das am wenigsten verifizierte Paar in dieser Codebasis (siehe Warnung am Anfang von lib/fatsecret/exercise.ts) — überprüfe den genauen Methodennamen/die Parameter gegen https://platform.fatsecret.com/docs/guides, bevor du dich darauf verlässt; es könnten echte Korrekturen nötig sein, nicht nur eine Verifizierung.

8. Committe niemals echte FatSecret-Zugangsdaten und führe diese Checkliste niemals in CI aus.

Umgebungsvariablen

Trage sie in den Umgebungsvariablen des Vercel-Projekts ein (Production + Preview). Committe niemals echte Werte — .env.example dokumentiert nur die Namen.

Bereitstellung

1. vercel link

2. vercel env add FATSECRET_CLIENT_ID (wiederhole dies für jede Variable in der obigen Tabelle, für die du einen Wert hast — mindestens FATSECRET_CLIENT_ID/SECRET, MCP_BEARER_TOKEN, OAUTH_CLIENT_ID/SECRET; füge das Paar FATSECRET_CONSUMER_*/FATSECRET_ACCESS_TOKEN* hinzu, sobald du das OAuth1-Einrichtungsskript ausgeführt hast)

3. Verbinde dieses GitHub-Repository im Vercel-Dashboard für automatisches Deployment bei Push auf main, oder führe vercel --prod manuell aus.

4. Notiere die bereitgestellte URL (prüfe Projekt → Einstellungen → Domains, da fatsecret-mcp.vercel.app im gemeinsamen Vercel-Namespace möglicherweise bereits vergeben ist).

5. Nimm die ausgehende IP dieses Deployments in die Allowlist auf in der FatSecret-Entwicklerkonsole für OAuth2-Token-Anfragen (siehe Setup-Schritt 1) — das ist der Schritt, der in der Produktion am ehesten Probleme verursacht, da Vercel-Serverless-Funktionen standardmäßig keine feste IP haben.

Mit Claude verbinden

Benutzerdefinierte Connectors können nur von claude.ai (Web) oder der Desktop-App hinzugefügt werden — nicht von der Mobile-App. Sobald sie dort hinzugefügt wurden, sind sie automatisch auch mobil nutzbar.

1. Auf claude.ai: Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen.

2. Name: FatSecret. URL: https://<your-deployment>/api/mcp.

3. Falls dein Konto die Beta-Funktion „Request headers“ hat: füge dort Authorization: Bearer <MCP_BEARER_TOKEN> hinzu und fahre mit Schritt 5 fort.

4. Andernfalls öffne die erweiterten Einstellungen und trage unter OAuth Client ID / OAuth Client Secret die Werte OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET ein, die in Vercel festgelegt wurden. Claude erkennt die Endpunkte /authorize und /token automatisch über die .well-known-Metadaten dieses Servers.

5. Speichern. Claude sollte die 17 Tools oben auflisten.

Versuche zu fragen: „バナナのカロリーを教えて“ (sag mir, wie viele Kalorien eine Banane hat), oder „今日の朝食にバナナを1本記録して“ (logge eine Banane für das heutige Frühstück — sobald Phase 3/4 eingerichtet und verifiziert sind).

Danksagungen

Das Design des 3-Leg-OAuth1-Flows wurde von fcoury/fatsecret-mcp (MIT) inspiriert, das den OAuth-Flow selbst als MCP-Tools bereitstellt; dieses Projekt führt ihn stattdessen einmalig als eigenständiges Einrichtungsskript (scripts/fatsecret-oauth-setup.ts) aus, da es für ein einzelnes persönliches FatSecret-Konto und nicht für die Nutzung durch mehrere Benutzer ausgelegt ist. Es wurde kein Code daraus übernommen.