node-huckleberry-mcp
This server provides an unofficial API for the Huckleberry baby tracker, enabling AI assistants to query, log, edit, and delete baby care records.
Child Management: Retrieve your user profile and child profiles (name, gender, birthdate).
Sleep Tracking: Log sleep sessions (start/end times), view history, edit, and delete entries.
Feeding Tracking: Log nursing sessions (left/right durations), bottle feeds (amount, type, units), and solids. View, edit, and delete feeding history.
Pumping Tracking: Record pumping sessions (left/right amounts, duration), view history, edit, and delete entries.
Diaper & Potty Tracking: Log diaper changes (pee, poo, both, or dry; with color, consistency, and amount) and potty training activity. View, edit, and delete entries.
Growth Tracking: Log measurements (weight, height, head circumference in metric or imperial), fetch the latest or full history, edit, and delete entries.
Food Database: Browse a curated food database, list child-specific custom foods, and create new custom food entries (with category, allergens, and notes).
Notes: All logged events support optional free-text notes.
Prompts: Pre-defined prompts for general usage, daily summaries, and generic event logging.
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-mcpOr use directly via npx:
npx node-huckleberry-mcpFrom source
git clone https://github.com/KenLSM/node-huckleberry-mcp.git
cd node-huckleberry-mcp
npm install
npm run build
node dist/index.jsRelated 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_YorkCreate a .env file in your project root (see .env.example for a template):
cp .env.example .env
# Edit .env with your Huckleberry credentialsNote: 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 |
| — | User profile + child UID list |
|
| Child profile ( |
Sleep (4)
Tool | Input | Purpose |
|
| Log a completed sleep session |
|
| Recent sleep sessions (incl. |
|
| Edit an existing sleep entry |
|
| Permanently delete a sleep entry |
Feeding (10)
Tool | Input | Purpose |
|
| Log a nursing session |
|
| Log a bottle feeding |
|
| Log a solids feeding |
|
| Log a pumping session |
|
| Recent pump sessions (incl. |
|
| Recent feeds (incl. |
|
| Edit an existing feed entry |
|
| Edit an existing pump entry |
|
| Permanently delete a feed entry |
|
| 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 a diaper change |
|
| Log potty training activity |
|
| Diaper + potty history (incl. |
|
| Edit an existing diaper/potty entry |
|
| Permanently delete a diaper/potty entry |
Growth (5)
Tool | Input | Purpose |
|
| Log a growth measurement |
|
| Most recent growth measurement (incl. |
|
| Growth history (incl. |
|
| Edit an existing growth measurement |
|
| Permanently delete a growth measurement |
Solids — custom foods (3)
Tool | Input | Purpose |
| — | Fetch the curated food database |
|
| List custom foods for a child |
|
| Create a custom food entry |
All
start/endinputs are epoch seconds. Times are stored with a timezoneoffsetderived fromHUCKLEBERRY_TIMEZONE.Every
log_*tool accepts an optional free-textnotesfield, which is stored on the entry and returned by the matching history/get_*tool (each read entry includes its Firestoreid). Theedit_*tools (edit_sleep,edit_feed,edit_pump,edit_diaper,edit_growth) updatenotesand other fields on an existing entry, and thedelete_*tools remove one — both take theid/interval_id/entry_idfrom the matching read. Deleting does not recompute the tracker'sprefs.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 pointSee AGENTS.md for architecture details and conventions.
Testing
Unit tests are in src/__tests__/ and use Vitest with Firebase mocked:
npm testRun a single test file:
npm test -- models.test.tsWatch mode:
npm run test:watchLive 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:integrationLicensing & Attribution
This project is a Node.js port of two MIT-licensed projects:
py-huckleberry-api© 2025 Woyken (GitHub, MIT License)py-huckleberry-mcp© 2026 Huckleberry MCP Contributors (GitHub, MIT License)
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
.envor 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 toolscreate_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
Scored across 29 tools
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.
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.
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.
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
Related MCP Connectors
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
Hosted Apple Health MCP for Claude and ChatGPT, works outside the US. iPhone app, no local server.
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseAqualityAmaintenanceAn 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.27739 PyPI28MIT
- AlicenseNot gradedqualityBmaintenanceMCP server that connects AI assistants like Claude to WHOOP health data, enabling natural language queries about recovery, sleep, workouts, and more.282 npm183MIT
- AlicenseAqualityDmaintenanceFirst MCP server for the Procare Connect API, enabling querying child care center data (attendance, enrollments, family balances, etc.) via natural language from Claude, Cursor, or any MCP client.16MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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