Huckleberry MCP Server

Inoffizieller Huckleberry Baby-Tracker-MCP-Server für Claude, Cursor, VS Code und andere KI-Assistenten. Baby-Schlaf, Fütterungen, Windeln, Abpumpen, feste Nahrung, Töpfchen und Wachstumsdaten abfragen und protokollieren.

Huckleberry-Daten (Schlaf, Fütterung, Wachstum, Windeln, feste Nahrung) direkt in Claude Desktop verfügbar machen oder den MCP-Server in andere KI-Anwendungen integrieren.

Installation

Voraussetzungen

• Node.js 24+ (entspricht CI; siehe .nvmrc)

• npm 9+

Schnellstart

npm install -g node-huckleberry-mcp

Oder direkt über npx verwenden:

npx node-huckleberry-mcp

Aus dem Quellcode

git clone https://github.com/KenLSM/node-huckleberry-mcp.git
cd node-huckleberry-mcp
npm install
npm run build
node dist/index.js

Related MCP server: whoop-ai-mcp

Konfiguration

Umgebungsvariablen

Der Server liest die Anmeldedaten aus Umgebungsvariablen:

HUCKLEBERRY_EMAIL=you@example.com
HUCKLEBERRY_PASSWORD=your-password
HUCKLEBERRY_TIMEZONE=America/New_York

Erstelle eine .env-Datei im Projektstamm (siehe .env.example als Vorlage):

cp .env.example .env
# Edit .env with your Huckleberry credentials

Hinweis: Committe .env niemals in die Versionskontrolle. Die .gitignore schließt sie bereits aus.

Claude Desktop-Integration

Um diesen Server mit Claude Desktop zu verwenden, füge ihn zu deiner claude_desktop_config.json hinzu:

macOS/Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "huckleberry": {
      "command": "npx",
      "args": ["node-huckleberry-mcp"],
      "env": {
        "HUCKLEBERRY_EMAIL": "you@example.com",
        "HUCKLEBERRY_PASSWORD": "your-password",
        "HUCKLEBERRY_TIMEZONE": "America/New_York"
      }
    }
  }
}

Starte Claude Desktop nach dem Aktualisieren der Konfiguration neu. Die Huckleberry-Tools erscheinen in der Werkzeugliste.

Tools

Der Server stellt 29 Tools in 6 Kategorien bereit. (Timer für aktive Sitzungen – start_sleep, pause_feeding usw. – sind nicht implementiert; verwende die expliziten log_*-Tools, um abgeschlossene Ereignisse zu protokollieren.)

Kindverwaltung (2)

Schlaf (4)

Fütterung (10)

Windel (5)

color und consistency sind auf eine feste Wertemenge beschränkt (gelb/braun/grün/schwarz/rot/weiß/orange/sonstiges; hart/normal/weich/breiig/wässrig/geformt/schleimig), um zu verhindern, dass ein nicht erkanntes Wert die Huckleberry-App bei diesem Eintrag zum Absturz bringt. Siehe TASKS.md → BUG2, wie die Menge ausgewählt wurde – aus dem Legacy-Port übernommen, noch nicht live bestätigt.

Wachstum (5)

Feste Nahrung – benutzerdefinierte Lebensmittel (3)

Alle start/end-Eingaben sind Epochensekunden. Zeiten werden mit einem Zeitzonen-offset gespeichert, der aus HUCKLEBERRY_TIMEZONE abgeleitet wird.

Jedes log_*-Tool akzeptiert ein optionales Freitextfeld notes, das im Eintrag gespeichert und vom passenden Verlaufs-/get_*-Tool zurückgegeben wird (jeder gelesene Eintrag enthält seine Firestore-id). Die edit_*-Tools (edit_sleep, edit_feed, edit_pump, edit_diaper, edit_growth) aktualisieren notes und andere Felder eines vorhandenen Eintrags, und die delete_*-Tools entfernen einen – beide verwenden die id/interval_id/entry_id aus dem passenden Lesevorgang. Beim Löschen wird die prefs.last*-Zusammenfassung des Trackers nicht neu berechnet, sodass eine „Zuletzt"-Ansicht einen gelöschten Eintrag kurzzeitig anzeigen kann, bis der nächste Schreibvorgang erfolgt.

Prompts

Der Server stellt außerdem MCP-Prompts bereit (Slash-Command-Vorlagen in Clients, die diese unterstützen): huckleberry_usage (lädt die Nutzungskonventionen), daily_summary (date?) und log_event (event).

Agent-Fähigkeit

skills/huckleberry/SKILL.md lehrt einem Assistenten, diese Tools korrekt zu verwenden (Kind-Auflösung, natürliche Sprache → Epochensekunden, Einheiten, Bestätigung vor dem Schreiben). Kopiere sie in dein Claude-Skills-Verzeichnis, um die MCP-Nutzung zu vereinfachen.

Entwicklung

Skripte

npm run build            # TypeScript → JavaScript (tsc)
npm run lint             # Lint with oxlint
npm run lint:fix         # Lint and auto-fix
npm run format           # Format with oxfmt
npm run format:check     # Check formatting without changes
npm test                 # Run unit tests (Vitest)
npm run test:watch       # Watch mode for tests
npm run test:integration # Live tests (needs HUCKLEBERRY_* creds; skipped otherwise). Read-only by default; set HUCKLEBERRY_ALLOW_WRITES=1 to also run the log_*→delete write round-trip (test account only)
npm run inspect:schema   # Dump real Firestore shapes (needs creds) — see docs/integration-testing.md
npm run smoke            # Build + run the MCP server smoke test
npm run dev              # Run in dev mode (tsx)

Toolchain

• TypeScript 5.3+ im Strict-Modus

• oxc (oxlint + oxfmt) – schnelles, auf Rust basierendes Linting & Formatieren

• Vitest – Unit-Test-Runner

• Zod – Laufzeit-Validierung

• Firebase JS SDK – Firestore + Auth

Architektur

src/
├── auth/            # Authentication (T1.1)
├── client/          # Huckleberry API operations (T1.2–T1.9)
├── models/          # Zod schemas for Firestore docs (T1.3)
├── server/          # MCP server framework (T2.1–T2.2)
├── tools/           # MCP tool implementations (T2.3–T2.8)
├── __tests__/       # Unit & smoke tests
└── index.ts         # Entry point

Siehe AGENTS.md für Architekturdetails und Konventionen.

Testen

Unit-Tests befinden sich in src/__tests__/ und verwenden Vitest mit gemocktem Firebase:

npm test

Eine einzelne Testdatei ausführen:

npm test -- models.test.ts

Watch-Modus:

npm run test:watch

Live-Integration (geschützt) validiert gegen ein echtes Konto und wird ohne Anmeldedaten übersprungen. Sie ist standardmäßig schreibgeschützt; ein optionaler log_*→delete-Schreib-Roundtrip läuft nur mit HUCKLEBERRY_ALLOW_WRITES=1 (ein Testkonto verwenden) – siehe docs/integration-testing.md:

# read-only schema validation
HUCKLEBERRY_EMAIL=… HUCKLEBERRY_PASSWORD=… npm run test:integration

# also exercise log_*→delete writes (test account only)
HUCKLEBERRY_EMAIL=… HUCKLEBERRY_PASSWORD=… HUCKLEBERRY_ALLOW_WRITES=1 npm run test:integration

Lizenz & Namensnennung

Dieses Projekt ist ein Node.js-Port von zwei MIT-lizenzierten Projekten:

• py-huckleberry-api © 2025 Woyken (GitHub, MIT-Lizenz)

• py-huckleberry-mcp © 2026 Huckleberry MCP Contributors (GitHub, MIT-Lizenz)

Dieser Port enthält wesentliches Design und Implementierung aus beiden Upstream-Projekten.

Sicherheit & Datenschutz

• Es werden keine Daten lokal gespeichert. Alle Vorgänge sind authentifizierte Lese-/Schreibzugriffe auf deine Huckleberry-Firestore-Datenbank.

• Anmeldedaten basieren auf Umgebungsvariablen. Committe niemals .env und hinterlege keine Anmeldedaten im Code.

• Dies ist ein inoffizieller Client eines Drittanbieter-Dienstes; die API ist reverse-engineered und kann sich ändern.

Support

• Dokumentation: Siehe AGENTS.md für Mitwirkenden-Hinweise.

• Probleme: Melde Fehler oder fordere Funktionen über GitHub Issues an.

• Upstream: Bei Fragen zu Huckleberry-Daten oder API-Änderungen siehe die ursprünglichen Python-Projekte.

Erstellt mit ❤️ als Node/TypeScript-Port von py-huckleberry-api und py-huckleberry-mcp.