Huckleberry MCP サーバー

Huckleberry ベビートラッカーの非公式 MCP サーバーです。Claude、Cursor、VS Code、その他の AI アシスタントに対応しています。赤ちゃんの睡眠、授乳、おむつ、搾乳、固形食、トイレトレーニング、成長記録の照会・記録ができます。

Huckleberry のデータ（睡眠、授乳、成長、おむつ、固形食）を Claude Desktop に直接公開したり、MCP サーバーを他の AI アプリケーションに統合したりできます。

インストール

必要条件

• Node.js 24 以上（CI と一致。.nvmrc を参照）

• npm 9 以上

クイックスタート

npm install -g node-huckleberry-mcp

または npx で直接使用:

npx node-huckleberry-mcp

ソースから

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

設定

環境変数

サーバーは環境変数から認証情報を読み取ります:

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

プロジェクトのルートに .env ファイルを作成します（テンプレートは .env.example を参照）:

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

注: .env をバージョン管理にコミットしないでください。.gitignore で既に除外されています。

Claude Desktop 連携

このサーバーを Claude Desktop で使用するには、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"
      }
    }
  }
}

設定を更新したら、Claude Desktop を再起動してください。Huckleberry のツールがツール一覧に表示されます。

ツール

サーバーは 6 カテゴリ・29 ツール を公開しています。（アクティブセッションの睡眠・授乳タイマー — start_sleep、pause_feeding など — は実装されていません。完了したイベントの記録には明示的な log_* ツールを使用してください。）

子どもの管理（2）

睡眠（4）

授乳（10）

おむつ（5）

color と consistency は固定の値セット（yellow/brown/green/black/red/white/orange/other; hard/normal/soft/runny/watery/formed/mucousy）に制限されており、未認識の値が Huckleberry アプリをクラッシュさせるのを防ぎます。このセットの選定方法は TASKS.md → BUG2 を参照してください — レガシーポートから採用されたもので、まだ実環境で確認されていません。

成長（5）

固形食 — カスタムフード（3）

すべての start/end 入力は エポック秒 です。時刻は HUCKLEBERRY_TIMEZONE から導出されたタイムゾーン offset とともに保存されます。

すべての log_* ツールはオプションの自由記述 notes フィールドを受け付け、エントリに保存され、対応する履歴/get_* ツールで返されます（各読み取りエントリには Firestore の id が含まれます）。edit_* ツール（edit_sleep、edit_feed、edit_pump、edit_diaper、edit_growth）は既存のエントリの notes やその他のフィールドを更新し、delete_* ツールはエントリを 1 つ削除します — どちらも対応する読み取りから id/interval_id/entry_id を取得します。削除してもトラッカーの prefs.last* サマリーは再計算されないため、「最新」ビューに削除されたエントリが次の書き込みまで一時的に表示されることがあります。

プロンプト

サーバーは MCP プロンプト（対応クライアントでのスラッシュコマンド形式のテンプレート）も公開しています: huckleberry_usage（使用規則を読み込む）、daily_summary（date?）、log_event（event）。

エージェントスキル

skills/huckleberry/SKILL.md は、アシスタントにこれらのツールの正しい使い方（子の解決、自然言語の時刻 → エポック秒、単位、書き込み前の確認）を教えます。Claude のスキルディレクトリにコピーすると、MCP をよりスムーズに使用できます。

開発

スクリプト

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)

ツールチェーン

• TypeScript 5.3+（strict モード）

• oxc（oxlint + oxfmt）— 高速な Rust ベースの lint とフォーマット

• Vitest — ユニットテストランナー

• Zod — ランタイムデータ検証

• Firebase JS SDK — Firestore + Auth

アーキテクチャ

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

アーキテクチャの詳細と規約については AGENTS.md を参照してください。

テスト

ユニットテストは src/__tests__/ にあり、Firebase をモックした Vitest を使用します:

npm test

単一のテストファイルを実行:

npm test -- models.test.ts

ウォッチモード:

npm run test:watch

ライブ統合テスト（ゲート付き）は実際のアカウントに対して検証し、認証情報がない場合はスキップされます。デフォルトでは読み取り専用で、オプトインの log_*→delete 書き込みラウンドトリップは HUCKLEBERRY_ALLOW_WRITES=1 の場合のみ実行されます（テストアカウントを使用してください）— 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

ライセンスと帰属

このプロジェクトは、MIT ライセンスの 2 つのプロジェクトの Node.js ポートです:

• py-huckleberry-api © 2025 Woyken（GitHub、MIT License）

• py-huckleberry-mcp © 2026 Huckleberry MCP Contributors（GitHub、MIT License）

このポートには、両方のアップストリームプロジェクトの設計と実装が大幅に含まれています。

安全性とプライバシー

• データはローカルに保存されません。 すべての操作は、Huckleberry Firestore データベースへの認証付き読み取り/書き込みです。

• 認証情報は環境ベースです。 .env をコミットしたり、認証情報をハードコードしたりしないでください。

• これはサードパーティサービスの非公式クライアントであり、API はリバースエンジニアリングされたもので、変更される可能性があります。

サポート

• ドキュメント: コントリビューター向けガイダンスは AGENTS.md を参照してください。

• 問題: バグの報告や機能のリクエストは GitHub Issues で行ってください。

• アップストリーム: Huckleberry のデータや API の変更に関する質問は、元の Python プロジェクトを参照してください。

❤️を込めて、py-huckleberry-api と py-huckleberry-mcp の Node/TypeScript 移植版として構築されました。