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 18+ (CI runs on Node 24)
• 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

Configuration

Environment Variables

The server reads credentials from environment variables:

[email protected]
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": "[email protected]",
        "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 24 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 (3)

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

Feeding (8)

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

Diaper (4)

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

Growth (4)

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

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 — pass the id/interval_id/entry_id from the matching read.

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:

• 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 .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.