Skip to main content
Glama
node-huckleberry-mcp

node-huckleberry-mcp

npm version npm downloads

Huckleberry MCP Server

Unofficial Huckleberry baby tracker MCP server for Claude, Cursor, VS Code, and other AI assistants. Query and log baby sleep, feeds, diapers, pumping, solids, potty, and growth records.

Expose Huckleberry's data (sleep, feeding, growth, diapers, solids) directly in Claude Desktop, or integrate the MCP server into other AI applications.

Installation

Requirements

  • Node.js 24+ (matches CI; see .nvmrc)

  • npm 9+

Quick Start

npm install -g node-huckleberry-mcp

Or use directly via npx:

npx node-huckleberry-mcp

From source

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

Configuration

Environment Variables

The server reads credentials from environment variables:

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

Create a .env file in your project root (see .env.example for a template):

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

Note: Never commit .env to version control. The .gitignore already excludes it.

Claude Desktop Integration

To use this server with Claude Desktop, add it to your claude_desktop_config.json:

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"
      }
    }
  }
}

After updating the config, restart Claude Desktop. The Huckleberry tools will appear in the tool list.

Tools

The server exposes 29 tools across 6 categories. (Active-session sleep/feed timers — start_sleep, pause_feeding, etc. — are not implemented; use the explicit log_* tools to record completed events.)

Child Management (2)

Tool

Input

Output

get_user

—

User profile + child UID list

get_child

child_uid

Child profile (childsName, gender, birthdate)

Sleep (4)

Tool

Input

Purpose

log_sleep

child_uid, start, end (epoch s), notes?

Log a completed sleep session

get_sleep_history

child_uid, limit?

Recent sleep sessions (incl. id)

edit_sleep

child_uid, interval_id, + any of start/duration/notes

Edit an existing sleep entry

delete_sleep

child_uid, interval_id

Permanently delete a sleep entry

Feeding (10)

Tool

Input

Purpose

log_nursing

child_uid, start, left_duration?, right_duration?, last_side?, notes?

Log a nursing session

log_bottle

child_uid, start, amount, bottle_type, units, notes?

Log a bottle feeding

log_solids

child_uid, start, notes?

Log a solids feeding

log_pump

child_uid, start, left_amount/right_amount or total_amount, units, duration?, notes?

Log a pumping session

list_pump_intervals

child_uid, limit?

Recent pump sessions (incl. id)

get_feed_history

child_uid, limit?

Recent feeds (incl. id), newest first

edit_feed

child_uid, interval_id, + any of start/amount/bottle_type/units/left_duration/right_duration/last_side/notes

Edit an existing feed entry

edit_pump

child_uid, interval_id, + any of start/left_amount/right_amount/units/duration/notes

Edit an existing pump entry

delete_feed

child_uid, interval_id

Permanently delete a feed entry

delete_pump

child_uid, interval_id

Permanently delete a pump entry

Diaper (5)

color and consistency are restricted to a fixed set of values (yellow/brown/green/black/red/white/orange/other; hard/normal/soft/runny/watery/formed/mucousy) to prevent an unrecognized value from crashing the Huckleberry app on that entry. See TASKS.md → BUG2 for how the set was chosen — adopted from the legacy port, not yet live-confirmed.

Tool

Input

Purpose

log_diaper

child_uid, mode (pee/poo/both/dry), start, color?, consistency?, pee_amount?, poo_amount?, notes?

Log a diaper change

log_potty

child_uid, mode (pee/poo), start, notes?

Log potty training activity

get_diaper_history

child_uid, limit?

Diaper + potty history (incl. id)

edit_diaper

child_uid, interval_id, + any of start/mode/color/consistency/pee_amount/poo_amount/notes

Edit an existing diaper/potty entry

delete_diaper

child_uid, interval_id

Permanently delete a diaper/potty entry

Growth (5)

Tool

Input

Purpose

log_growth

child_uid, weight?, height?, head?, units? (metric/imperial), start?, notes?

Log a growth measurement

get_latest_growth

child_uid

Most recent growth measurement (incl. id)

get_growth_history

child_uid, limit?

Growth history (incl. id)

edit_growth

child_uid, entry_id, + any of start/weight/height/head/units/notes

Edit an existing growth measurement

delete_growth

child_uid, entry_id

Permanently delete a growth measurement

Solids — custom foods (3)

Tool

Input

Purpose

list_curated_foods

—

Fetch the curated food database

list_custom_foods

child_uid

List custom foods for a child

create_custom_food

child_uid, name, category?, allergens?, notes?

Create a custom food entry

All start/end inputs are epoch seconds. Times are stored with a timezone offset derived from HUCKLEBERRY_TIMEZONE.

Every log_* tool accepts an optional free-text notes field, which is stored on the entry and returned by the matching history/get_* tool (each read entry includes its Firestore id). The edit_* tools (edit_sleep, edit_feed, edit_pump, edit_diaper, edit_growth) update notes and other fields on an existing entry, and the delete_* tools remove one — both take the id/interval_id/entry_id from the matching read. Deleting does not recompute the tracker's prefs.last* summary, so a "most recent" view may briefly show a deleted entry until the next write.

Prompts

The server also exposes MCP prompts (slash-command-style templates in clients that support them): huckleberry_usage (loads the usage conventions), daily_summary (date?), and log_event (event).

Agent skill

skills/huckleberry/SKILL.md teaches an assistant how to use these tools correctly (child resolution, natural-language time → epoch seconds, units, confirm-before-write). Copy it into your Claude skills directory to make the MCP smoother to use.

Development

Scripts

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+ with strict mode

  • oxc (oxlint + oxfmt) — fast, Rust-based linting & formatting

  • Vitest — unit test runner

  • Zod — runtime data validation

  • Firebase JS SDK — Firestore + Auth

Architecture

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

See AGENTS.md for architecture details and conventions.

Testing

Unit tests are in src/__tests__/ and use Vitest with Firebase mocked:

npm test

Run a single test file:

npm test -- models.test.ts

Watch mode:

npm run test:watch

Live integration (gated) validates against a real account and is skipped without credentials. It is read-only by default; an opt-in log_*→delete write round-trip runs only with HUCKLEBERRY_ALLOW_WRITES=1 (use a test account) — see 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

Licensing & Attribution

This project is a Node.js port of two MIT-licensed projects:

This port includes substantial design and implementation from both upstream projects.

Safety & Privacy

  • No data is stored locally. All operations are authenticated reads/writes to your Huckleberry Firestore database.

  • Credentials are environment-based. Never commit .env or hardcode credentials.

  • This is an unofficial client of a third-party service; the API is reverse-engineered and may change.

Support

  • Documentation: See AGENTS.md for contributor guidance.

  • Issues: Report bugs or request features on GitHub Issues.

  • Upstream: For questions about Huckleberry data or API changes, see the original Python projects.


Built with ❤️ as a Node/TypeScript port of py-huckleberry-api and py-huckleberry-mcp.

Available Tools

29 tools
create_custom_foodC

Create a custom food entry for a child

Inputs: name (required), child_uid (required), category, allergens.

delete_diaperA

Permanently delete a diaper or potty entry. Get the interval_id from get_diaper_history first.

Inputs: child_uid (required), interval_id (required).

delete_feedA

Permanently delete a feed entry (nursing/bottle/solids). Get the interval_id from get_feed_history first.

Inputs: child_uid (required), interval_id (required).

delete_growthA

Permanently delete a growth measurement. Get the entry id from get_growth_history or get_latest_growth first.

Inputs: entry_id (required), child_uid (required).

delete_pumpA

Permanently delete a pump entry. Get the interval_id from list_pump_intervals first.

Inputs: child_uid (required), interval_id (required).

delete_sleepA

Permanently delete a sleep entry. Get the interval_id from get_sleep_history first.

Inputs: child_uid (required), interval_id (required).

edit_diaperB

Edit an existing diaper or potty entry. Get the interval_id from get_diaper_history first.

Inputs: child_uid (required), interval_id (required), mode, color, +5 more.

edit_feedB

Edit an existing feed entry. Get the interval_id from get_feed_history first.

Inputs: child_uid (required), interval_id (required), notes, start, +6 more.

edit_growthB

Edit an existing growth measurement. Get the entry id from get_growth_history or get_latest_growth first.

Inputs: entry_id (required), child_uid (required), head, notes, +4 more.

edit_pumpC

Edit an existing pump entry. Get the interval_id from list_pump_intervals first.

Inputs: child_uid (required), interval_id (required), notes, start, +4 more.

edit_sleepA

Edit an existing sleep entry. Get the interval_id from get_sleep_history first.

Inputs: child_uid (required), interval_id (required), notes, start, +1 more.

get_childB

Retrieve a specific child's profile by their UID

Inputs: child_uid (required).

get_diaper_historyB

Get diaper and potty history for a child, most recent first

Inputs: child_uid (required), limit.

get_feed_historyC

Retrieve feeding history for a child

Inputs: child_uid (required), limit.

get_growth_historyC

Get growth measurement history for a child, most recent first

Inputs: child_uid (required), limit.

get_latest_growthC

Get the most recent growth measurement for a child

Inputs: child_uid (required).

get_sleep_historyC

Retrieve sleep history for a child

Inputs: child_uid (required), limit.

get_userA

Retrieve the authenticated user's profile including the list of children they manage

Inputs: no named parameters.

list_curated_foodsC

Retrieve the list of curated foods from the food database

Inputs: limit.

list_custom_foodsC

Retrieve custom foods created for a child

Inputs: child_uid (required).

list_pump_intervalsC

Retrieve pump sessions for a child

Inputs: child_uid (required), limit.

log_bottleC

Log a bottle feeding

Inputs: start (required), units (required), amount (required), child_uid (required), +2 more.

log_diaperC

Log a diaper change for a child

Inputs: mode (required), start (required), child_uid (required), color, +4 more.

log_growthC

Log a growth measurement (any of weight, height, head circumference)

Inputs: child_uid (required), head, notes, start, +3 more.

log_nursingC

Log a nursing session

Inputs: start (required), child_uid (required), notes, last_side, +2 more.

log_pottyC

Log potty training activity for a child

Inputs: mode (required), start (required), child_uid (required), notes.

log_pumpD

Log a pumping session

Inputs: start (required), units (required), child_uid (required), left_amount (required), +4 more.

log_sleepB

Log a completed sleep session with start and end times

Inputs: end (required), start (required), child_uid (required), notes.

log_solidsC

Log a solids feeding

Inputs: start (required), child_uid (required), notes.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 29 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action. Even with many log_* tools, each is specific to a type (diaper, potty, nursing, bottle, solids, pump, sleep, growth) with clear descriptions. Edits and deletes explicitly reference the history tool to fetch the correct ID, eliminating ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with underscores (e.g., log_diaper, get_growth_history, edit_pump). Verbs are uniform (log, get, edit, delete, create, list), and there is no mixing of conventions or camelCase.

    Tool Count2/5

    With 29 tools, the count exceeds the 25+ threshold and feels heavy. While the domain is broad, some tools could be consolidated (e.g., get_latest_growth vs. get_growth_history, and separate pump vs. feed tools), suggesting bloat. The number overtaxes an agent's selection space.

    Completeness3/5

    The surface covers many domains but has notable gaps: custom foods lack edit/delete operations, and child management only has get_child, with no create/update/delete. This leaves dead ends and prevents full lifecycle management, though core feeding, sleep, and diaper tracking are complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      An MCP server that provides access to Cronometer nutrition data, enabling users to pull food logs, macro and micronutrient summaries, and biometric data into Claude or Cursor. It supports daily nutrition tracking and raw CSV exports by interfacing with the Cronometer web protocol.
      27
      739 PyPI
      28
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes personal device data from sources like Oura into a unified SQLite store, allowing Claude to answer questions across metrics (sleep, activity, etc.) with a set of read-only tools.
      MIT