Huckleberry MCP Server

Servidor MCP no oficial de Huckleberry baby tracker para Claude, Cursor, VS Code y otros asistentes de IA. Consulta y registra registros de sueño, alimentación, pañales, extracción de leche, sólidos, baño y crecimiento del bebé.

Expón los datos de Huckleberry (sueño, alimentación, crecimiento, pañales, sólidos) directamente en Claude Desktop, o integra el servidor MCP en otras aplicaciones de IA.

Instalación

Requisitos

• Node.js 24+ (coincide con CI; ver .nvmrc)

• npm 9+

Inicio rápido

npm install -g node-huckleberry-mcp

O úsalo directamente con npx:

npx node-huckleberry-mcp

Desde el código fuente

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

Configuración

Variables de entorno

El servidor lee las credenciales de las variables de entorno:

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

Crea un archivo .env en la raíz de tu proyecto (consulta .env.example para una plantilla):

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

Nota: Nunca subas .env al control de versiones. El .gitignore ya lo excluye.

Integración con Claude Desktop

Para usar este servidor con Claude Desktop, agrégalo a tu 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"
      }
    }
  }
}

Después de actualizar la configuración, reinicia Claude Desktop. Las herramientas de Huckleberry aparecerán en la lista de herramientas.

Herramientas

El servidor expone 29 herramientas en 6 categorías. (Los temporizadores de sueño/alimentación de sesión activa — start_sleep, pause_feeding, etc. — no están implementados; usa las herramientas explícitas log_* para registrar eventos completados).

Gestión de niños (2)

Sueño (4)

Alimentación (10)

Pañal (5)

color y consistency están restringidos a un conjunto fijo de valores (yellow/brown/green/black/red/white/orange/other; hard/normal/soft/runny/watery/formed/mucousy) para evitar que un valor no reconocido provoque un fallo en la aplicación Huckleberry en esa entrada. Consulta TASKS.md → BUG2 para saber cómo se eligió el conjunto — adoptado del puerto heredado, aún no confirmado en vivo.

Crecimiento (5)

Sólidos — alimentos personalizados (3)

Todas las entradas start/end son segundos de época. Las horas se almacenan con un offset de zona horaria derivado de HUCKLEBERRY_TIMEZONE.

Cada herramienta log_* acepta un campo opcional de texto libre notes, que se almacena en la entrada y se devuelve mediante la herramienta de historial/get_* correspondiente (cada entrada leída incluye su id de Firestore). Las herramientas edit_* (edit_sleep, edit_feed, edit_pump, edit_diaper, edit_growth) actualizan notes y otros campos en una entrada existente, y las herramientas delete_* eliminan una — ambas toman el id/interval_id/entry_id de la lectura correspondiente. Eliminar no recalcula el resumen prefs.last* del rastreador, por lo que una vista "más reciente" puede mostrar brevemente una entrada eliminada hasta la siguiente escritura.

Prompts

El servidor también expone prompts de MCP (plantillas de estilo comando de barra en clientes que los admiten): huckleberry_usage (carga las convenciones de uso), daily_summary (date?) y log_event (event).

Habilidad de agente

skills/huckleberry/SKILL.md enseña a un asistente cómo usar estas herramientas correctamente (resolución de niño, tiempo en lenguaje natural → segundos de época, unidades, confirmar antes de escribir). Cópialo en tu directorio de habilidades de Claude para que el MCP sea más fácil de usar.

Desarrollo

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)

Cadena de herramientas

• TypeScript 5.3+ con modo estricto

• oxc (oxlint + oxfmt) — linting y formateo rápidos basados en Rust

• Vitest — ejecutor de pruebas unitarias

• Zod — validación de datos en tiempo de ejecución

• Firebase JS SDK — Firestore + Auth

Arquitectura

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

Consulta AGENTS.md para detalles de arquitectura y convenciones.

Pruebas

Las pruebas unitarias están en src/__tests__/ y usan Vitest con Firebase simulado:

npm test

Ejecuta un solo archivo de prueba:

npm test -- models.test.ts

Modo de observación:

npm run test:watch

Integración en vivo (restringida) valida contra una cuenta real y se omite sin credenciales. Es de solo lectura por defecto; un ciclo de escritura log_*→delete opcional se ejecuta solo con HUCKLEBERRY_ALLOW_WRITES=1 (usa una cuenta de prueba) — consulta 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

Licencia y atribución

Este proyecto es un puerto de Node.js de dos proyectos con licencia MIT:

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

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

Este puerto incluye diseño e implementación sustanciales de ambos proyectos originales.

Seguridad y privacidad

• No se almacenan datos localmente. Todas las operaciones son lecturas/escrituras autenticadas a tu base de datos de Firestore de Huckleberry.

• Las credenciales se basan en el entorno. Nunca subas .env ni codifiques credenciales.

• Este es un cliente no oficial de un servicio de terceros; la API está diseñada mediante ingeniería inversa y puede cambiar.

Soporte

• Documentación: Consulta AGENTS.md para obtener orientación para contribuyentes.

• Problemas: Reporta errores o solicita funciones en GitHub Issues.

• Proyecto original: Para preguntas sobre los datos de Huckleberry o cambios en la API, consulta los proyectos originales en Python.

Construido con ❤️ como un port en Node/TypeScript de py-huckleberry-api y py-huckleberry-mcp.