Huckleberry MCP Server

Disclaimer: This is an unofficial, community-built project. It is not sponsored, endorsed, or supported by Huckleberry. Use at your own risk.

A Model Context Protocol (MCP) server built with FastMCP that interfaces with the Huckleberry baby tracking API, enabling Claude to help you track your baby’s sleep, feeding, diaper changes, and growth measurements through natural conversation.

Features

• Child Management: List and manage multiple child profiles
• Sleep Tracking: Start, pause, resume, complete, and cancel sleep sessions with automatic history tracking
• Feeding Tracking: Track breastfeeding sessions with side switching
• Diaper Logging: Record diaper changes with type, amount, color, and consistency details
• Growth Tracking: Log and retrieve weight, height, and head circumference measurements

Prerequisites

• Python 3.10 or higher
• A Huckleberry account with valid credentials
• Claude Desktop application (for integration)
• uv package manager (recommended) or pip

Installation

Using uv (Recommended)

# Clone or navigate to the project directory
cd /path/to/huckleberry-mcp
uv sync

Using pip

cd /path/to/huckleberry-mcp
pip install -e .

Architecture

This server uses the FastMCP framework for rapid MCP server development. FastMCP provides:

• Automatic tool registration via decorators
• Schema generation from type hints and docstrings
• Built-in error handling and protocol compliance
• Support for multiple transport types (STDIO, HTTP)

The server implements 22 tools across 5 categories:

• Child Management (2 tools)
• Sleep Tracking (7 tools)
• Feeding Tracking (8 tools)
• Diaper Tracking (2 tools)
• Growth Tracking (3 tools)

All tools use lazy authentication - credentials are validated on first tool use rather than at server startup.

Authentication Setup

The server requires your Huckleberry credentials to be configured as environment variables.

Claude Desktop Configuration (Recommended)

Add the server to your Claude Desktop configuration file with your credentials:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "huckleberry": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/huckleberry-mcp",
        "run",
        "huckleberry-mcp"
      ],
      "env": {
        "HUCKLEBERRY_EMAIL": "[email protected]",
        "HUCKLEBERRY_PASSWORD": "your-password",
        "HUCKLEBERRY_TIMEZONE": "America/New_York"
      }
    }
  }
}

Important:

• Replace /absolute/path/to/huckleberry-mcp with the actual absolute path to this project
• On macOS, if using Anaconda, specify the full path to uv: /Users/your-username/anaconda3/bin/uv
• Ensure uv is in your PATH or use the full path to the uv executable

Available Tools

Child Management

list_children

List all child profiles with their UID, name, and birth date.

Example: “List my children”

Sleep Tracking

log_sleep

Directly log a completed sleep session without using the timer. Useful for retroactive logging or importing past sleep data.

Parameters:

• child_uid (string, required): The child’s unique identifier
• start_time (string, required): Sleep start time in ISO format. If no timezone specified (e.g., “2026-01-30T14:30:00”), interpreted as your configured timezone. For UTC, use “2026-01-30T14:30:00Z”.
• end_time (string, optional): Sleep end time in ISO format (provide this OR duration_minutes). Same timezone handling as start_time.
• duration_minutes (integer, optional): Sleep duration in minutes (provide this OR end_time)

Timezone Note: Times without timezone info are interpreted using your HUCKLEBERRY_TIMEZONE setting (e.g., “America/New_York”). This ensures times appear correctly in the Huckleberry app.

Example: “Log a sleep session from 2pm to 4pm yesterday”

start_sleep

Begin a sleep tracking session for a child using real-time timer.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Start a sleep session for Alice”

pause_sleep

Pause an active sleep tracking session.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Pause the sleep session”

resume_sleep

Resume a paused sleep tracking session.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Resume the sleep session”

complete_sleep

Complete and save a sleep tracking session.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Complete the sleep session”

cancel_sleep

Cancel and discard a sleep tracking session.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Cancel the sleep session”

get_sleep_history

Get sleep history for a child within a date range (defaults to last 7 days).

Parameters:

• child_uid (string, required): The child’s unique identifier
• start_date (string, optional): Start date in ISO format (YYYY-MM-DD), inclusive
• end_date (string, optional): End date in ISO format (YYYY-MM-DD), exclusive (data up to but not including this date)

Important: The end_date is exclusive. To get data for a single day (e.g., Jan 30), set start_date='2026-01-30' and end_date='2026-01-31'.

Example: “Show me sleep history for the last week”

Feeding Tracking

log_breastfeeding

Directly log a completed breastfeeding session without using the timer. Useful for retroactive logging or importing past feeding data.

Parameters:

• child_uid (string, required): The child’s unique identifier
• start_time (string, required): Feeding start time in ISO format. If no timezone specified, interpreted as your configured timezone.
• left_duration_minutes (integer, optional): Duration on left breast in minutes
• right_duration_minutes (integer, optional): Duration on right breast in minutes
• end_time (string, optional): Feeding end time in ISO format (provide this OR durations)
• last_side (string, optional): Which side finished on (“left” or “right”). Required if using end_time.

Usage patterns:

• With durations: Provide left_duration_minutes and/or right_duration_minutes
• With end time: Provide end_time and last_side (calculates duration automatically)

Timezone Note: Times without timezone info are interpreted using your HUCKLEBERRY_TIMEZONE setting.

Examples:

• “Log a breastfeeding session from 2pm to 2:30pm yesterday on the left”
• “Log breastfeeding: 10 minutes left, 15 minutes right, starting at 3pm today”

start_breastfeeding

Begin a breastfeeding tracking session using real-time timer.

Parameters:

• child_uid (string, required): The child’s unique identifier
• side (string, required): Which side to start on (“left” or “right”)

Example: “Start breastfeeding on the left side”

pause_feeding

Pause an active feeding tracking session.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Pause feeding”

resume_feeding

Resume a paused feeding tracking session.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Resume feeding”

switch_feeding_side

Switch between left and right breast during breastfeeding.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Switch to the other side”

complete_feeding

Complete and save a feeding tracking session.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Complete feeding”

cancel_feeding

Cancel and discard a feeding tracking session.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “Cancel feeding”

get_feeding_history

Get feeding history for a child within a date range (defaults to last 7 days).

Parameters:

• child_uid (string, required): The child’s unique identifier
• start_date (string, optional): Start date in ISO format (YYYY-MM-DD), inclusive
• end_date (string, optional): End date in ISO format (YYYY-MM-DD), exclusive (data up to but not including this date)

Important: The end_date is exclusive. To get data for a single day (e.g., Jan 30), set start_date='2026-01-30' and end_date='2026-01-31'.

Example: “Show me today’s feedings”

Diaper Tracking

log_diaper

Log a diaper change with details. Supports retroactive logging with optional timestamp.

Parameters:

• child_uid (string, required): The child’s unique identifier
• mode (string, optional): Diaper mode (“pee”, “poo”, “both”, “dry”), default: “both”
• pee_amount (string, optional): Pee amount (“little”, “medium”, “big”)
• poo_amount (string, optional): Poo amount (“little”, “medium”, “big”)
• color (string, optional): Poo color if present (“yellow”, “brown”, “black”, “green”, “red”, “gray”)
• consistency (string, optional): Poo consistency if present (“solid”, “loose”, “runny”, “mucousy”, “hard”, “pebbles”, “diarrhea”)
• diaper_rash (boolean, optional): Whether baby has diaper rash, default: false
• notes (string, optional): Optional notes about the diaper change
• timestamp (string, optional): Timestamp in ISO format for retroactive logging. If not provided, uses current time.

Timezone Note: Times without timezone info are interpreted using your HUCKLEBERRY_TIMEZONE setting.

Examples:

• “Log a diaper change with pee and poo”
• “Log a wet diaper from 2 hours ago” (with retroactive timestamp)

get_diaper_history

Get diaper change history for a child within a date range (defaults to last 7 days).

Parameters:

• child_uid (string, required): The child’s unique identifier
• start_date (string, optional): Start date in ISO format (YYYY-MM-DD), inclusive
• end_date (string, optional): End date in ISO format (YYYY-MM-DD), exclusive (data up to but not including this date)

Important: The end_date is exclusive. To get data for a single day (e.g., Jan 30), set start_date='2026-01-30' and end_date='2026-01-31'.

Example: “Show me today’s diaper changes”

Growth Tracking

log_growth

Log growth measurements (weight, height, head circumference). Supports retroactive logging with optional timestamp.

Parameters:

• child_uid (string, required): The child’s unique identifier
• weight (number, optional): Weight (lbs if imperial, kg if metric)
• height (number, optional): Height (inches if imperial, cm if metric)
• head (number, optional): Head circumference (inches if imperial, cm if metric)
• units (string, optional): Measurement system (“imperial” or “metric”), default: “imperial”
• timestamp (string, optional): Timestamp in ISO format for retroactive logging. If not provided, uses current time.

Timezone Note: Times without timezone info are interpreted using your HUCKLEBERRY_TIMEZONE setting.

Examples:

• “Log weight of 12.5 lbs and height of 24 inches”
• “Log weight measurement from yesterday’s doctor visit” (with retroactive timestamp)

get_latest_growth

Get the latest growth measurements for a child.

Parameters:

• child_uid (string, required): The child’s unique identifier

Example: “What are the latest growth measurements?”

get_growth_history

Get growth measurement history for a child within a date range (defaults to last 30 days).

Parameters:

• child_uid (string, required): The child’s unique identifier
• start_date (string, optional): Start date in ISO format (YYYY-MM-DD), inclusive
• end_date (string, optional): End date in ISO format (YYYY-MM-DD), exclusive (data up to but not including this date)

Important: The end_date is exclusive. To get data for a single day (e.g., Jan 30), set start_date='2026-01-30' and end_date='2026-01-31'.

Example: “Show me growth history for the last month”

Usage Examples

Once configured in Claude Desktop, you can interact with the server through natural conversation:

1. List your children:

   • “List my children”
   • “Show me all my kids”

2. Track sleep:

   • “Log a sleep session from 2pm to 4pm yesterday” (direct logging)
   • “Log that Alice slept for 90 minutes starting at 1pm today” (direct logging)
   • “Start a sleep session for Alice” (real-time timer)
   • “Alice is sleeping”
   • “Pause the sleep timer”
   • “Alice woke up, complete the sleep session”
   • “Show me sleep history for the last week”

3. Track feeding:

   • “Log a breastfeeding session from 2pm to 2:30pm on the left” (direct logging)
   • “Log breastfeeding: 10 minutes left, 15 minutes right, starting at 3pm” (direct logging)
   • “Start breastfeeding on the left side” (real-time timer)
   • “Switch to the right breast”
   • “Complete the feeding session”
   • “Show me today’s feedings”

4. Log diaper changes:

   • “Log a diaper change with pee and poo”
   • “Log a wet diaper”
   • “Log a poopy diaper with loose yellow poo”
   • “Log a diaper change with medium poo and diaper rash”

5. Track growth:

   • “Log weight of 12.5 lbs”
   • “Log weight 12.5 lbs, height 24 inches, and head 16 inches”
   • “What are the latest growth measurements?”
   • “Show me growth history for the last month”

6. View history:

   • “Show me sleep history for last week”
   • “How many diaper changes today?”
   • “Show me all feedings from yesterday”

Development

Project Structure

src/huckleberry_mcp/
├── server.py          # FastMCP server instance and tool registration
├── auth.py            # Authentication handling (lazy singleton pattern)
├── utils.py           # Shared utilities (ISO timestamp conversion)
└── tools/             # Tool implementations
    ├── children.py    # Child management tools
    ├── sleep.py       # Sleep tracking tools
    ├── feeding.py     # Feeding/breastfeeding tools
    ├── diaper.py      # Diaper logging tools
    └── growth.py      # Growth measurement tools

Adding New Tools

To add a new tool:

1. Add the function to the appropriate module in tools/
2. Decorate with @mcp.tool()
3. Add comprehensive docstring (used for schema generation)
4. Use type hints for parameter validation
5. Register in server.py if creating new module

Example:

@mcp.tool()
async def my_new_tool(child_uid: str, data: str) -> Dict[str, Any]:
    """Tool description here.

    Args:
        child_uid: The child's unique identifier
        data: Some data parameter

    Returns:
        Status message and data
    """
    api = await get_authenticated_api()
    # Implementation...
    return {"success": True, "message": "Done"}

Running Tests

# Run all tests
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_sleep.py -v

# Run with coverage
uv run pytest tests/ --cov=huckleberry_mcp --cov-report=html

Dependencies

• fastmcp>=2.0.0,<3.0.0 - FastMCP framework for MCP server implementation
• huckleberry-api>=0.1.0 - Huckleberry API client library
• python-dotenv>=1.0.0 - Environment variable management

Implementation Notes

This server is fully refactored to match the actual py-huckleberry-api library interface:

• All history methods use Unix timestamps internally and convert to/from ISO dates
• Timer operations (sleep/feeding) directly call API methods without status pre-checks
• Growth tracking uses head parameter instead of head_circumference
• Diaper logging includes amount fields (pee_amount, poo_amount) and uses color instead of poo_color
• The server starts successfully even with invalid credentials, returning helpful errors when tools are called

Troubleshooting

Authentication Errors

If you see authentication errors when calling tools:

1. Verify your credentials are correct in the Claude Desktop config
2. Ensure your Huckleberry account is active and you can log in via the app
3. Check that the timezone is valid (e.g., “America/New_York”, “Europe/London”)
4. The server will start successfully but authentication happens when you call a tool

Server Not Appearing in Claude Desktop

1. Verify the configuration file path is correct for your OS
2. Check that the --directory path is absolute and correct
3. On macOS with Anaconda, use full path to uv: /Users/your-username/anaconda3/bin/uv
4. Restart Claude Desktop after making config changes
5. Check the Claude Desktop logs for error messages
6. Ensure uv is installed and accessible

Server Fails to Start

If you see “Failed to spawn process: No such file or directory”:

1. The uv command is not found - specify the full path to the uv executable
2. On macOS, find uv with: which uv or check /Users/your-username/anaconda3/bin/uv
3. Update the command field in your config to use the absolute path

Tools Not Working

1. Make sure you’ve listed children first to get valid child UIDs
2. Verify the child UID is correct when using tools
3. Timer sessions can be started/stopped without checking status first
4. Review error messages for specific validation issues (invalid colors, amounts, etc.)

Security Considerations

• Never commit your .env file or credentials to version control
• Store credentials only in environment variables or Claude Desktop config
• The .gitignore file excludes .env files by default
• Credentials are never logged by the server
• All API communication uses HTTPS

Contributing

This is a personal project, but suggestions and bug reports are welcome!

License

MIT License - See LICENSE file for details

Acknowledgments

• Built with the Model Context Protocol
• Uses the py-huckleberry-api Python library
• Powered by Claude from Anthropic

Migration History

v0.2.0 - FastMCP Migration (2026-01-31)

Migrated from raw MCP SDK to FastMCP framework:

• Reduced server.py from 442 to 47 lines
• Eliminated manual schema definitions (270+ lines)
• Consolidated duplicated timestamp utilities
• Preserved lazy authentication pattern
• Maintained all existing functionality

All existing tools and features remain unchanged for end users.

Support

For issues with:

• This MCP server: Open an issue in this repository
• The Huckleberry API library: See py-huckleberry-api
• Huckleberry app: Contact Huckleberry support
• Claude Desktop: See Anthropic documentation