Documentation

Complete guide to LoseIt MCP Server

Installation

Install the LoseIt MCP server with a single command:

curl -fsSL https://loseit.0x17.com/install.sh | sh

This downloads the binary for your platform, installs it to /usr/local/bin, and creates a config template at ~/.loseit-mcp/config.

Manual Installation

Download the appropriate binary for your system:

macOS (Apple Silicon): loseit-mcp-darwin-arm64
Linux (x86_64): loseit-mcp-linux-amd64
Linux (ARM64): loseit-mcp-linux-arm64

Make it executable with chmod +x and move to a directory in your PATH.

Configuration

The MCP server reads configuration from ~/.loseit-mcp/config. This file uses a simple key=value format:

# LoseIt MCP configuration
LOSEIT_USERNAME=your_email@example.com
LOSEIT_PASSWORD=your_password

# Optional: Apple Health export path
APPLE_HEALTH_EXPORT_PATH=/path/to/export.xml

Configuration Options

Setting	Required	Description
`LOSEIT_USERNAME`	Yes	Your LoseIt account email address
`LOSEIT_PASSWORD`	Yes	Your LoseIt account password
`APPLE_HEALTH_EXPORT_PATH`	No	Path to Apple Health export.xml file

Adding to Claude Code

After configuring, add the MCP server to Claude Code:

claude mcp add loseit -- loseit-mcp

Alternative: Environment Variables

You can also pass configuration via environment variables using claude mcp add-json:

claude mcp add-json loseit '{
  "command": "loseit-mcp",
  "env": {
    "LOSEIT_USERNAME": "your_email@example.com",
    "LOSEIT_PASSWORD": "your_password"
  }
}'

Data Storage

The MCP server stores all data in ~/.loseit-mcp/:

File	Description
`config`	Your credentials and settings
`tokens.json`	OAuth tokens (auto-managed)
`device.json`	Device ID for authentication
`cache.db`	SQLite cache of LoseIt data

Apple Health Setup

Apple Health integration enables body composition, vitals, sleep, and activity tracking. This is optional but recommended for comprehensive health insights.

Exporting Your Data

Open the Health app on your iPhone
Tap your profile picture in the top right
Scroll down and tap Export All Health Data
Wait for the export to complete (may take several minutes)
Save and transfer export.zip to your computer
Unzip to get export.xml

Configuring the Export Path

Add the path to your config file:

APPLE_HEALTH_EXPORT_PATH=/Users/you/Health/export.xml

Keeping Data Fresh

Apple Health data is static after export. To get the latest data:

Re-export from the Health app (weekly recommended)
Replace the old export.xml file
Use the refresh_apple_health tool to reload

Nutrition Tools

Core tools for tracking and analyzing your food intake from LoseIt.

get_daily

Get daily food log with meals, macros, and exercise for a specific date.

Parameters: date (YYYY-MM-DD format)

search_foods

Search your food history by name. Great for finding past meals.

Parameters: query, limit (optional)

get_weekly_summary

Get weekly aggregated stats including average calories, macros, exercise, and weight change.

Parameters: weeks (default: 4)

get_macro_breakdown

Get detailed macro analysis for a date range with protein/carb/fat ratios.

Parameters: start_date, end_date

get_goals

Get user goal settings including calorie budget, goal weight, and plan type.

Parameters: none

get_weight

Get weight tracking data from LoseIt over time.

Parameters: days (default: 30)

Key Concepts

Understanding the metrics used in analysis tools.

TDEE (Total Daily Energy Expenditure)

The total calories your body burns per day including all activity. Calculated from your actual weight loss: if you lost 1 lb, you had a ~3,500 calorie deficit over that period. TDEE = (food eaten + deficit) / days.

BMR (Basal Metabolic Rate)

Calories burned at complete rest—just to keep your body functioning. Estimated as TDEE minus exercise calories. Can also be calculated using the Mifflin-St Jeor formula with height, weight, age, and sex.

Calculated vs Formula BMR

Calculated BMR is derived from your actual weight loss data. Formula BMR uses standard equations. If calculated BMR is much higher than formula, you may be under-reporting food intake.

Net Calories

Food calories minus exercise calories burned. This is your effective caloric intake for the day.

Analysis Tools

Advanced analytics for understanding your nutrition patterns and progress.

get_energy_balance

Comprehensive energy balance analysis showing the complete picture of energy in vs energy out. Calculates food intake, exercise calories burned, net calories, and derives your TDEE and BMR from actual weight change. Shows how much of your deficit comes from eating less vs exercise.

Parameters: days (default: 30)
Outputs: avg food/exercise/net calories, calculated TDEE & BMR, deficit breakdown, weight change

get_tracking_accuracy

Analyze how accurately food is being tracked by comparing your calculated TDEE (derived from actual weight loss) against formula-based estimates using the Mifflin-St Jeor equation. Identifies missed logging days, suspiciously low-calorie days (<800 cal), and provides data quality warnings. Returns a tracking accuracy score showing if you may be under or over-reporting intake.

Parameters: days (default: 30), age (for formula comparison), sex (male/female), activity_level (sedentary/light/moderate/active/very_active)
Outputs: days logged/missed, low calorie days, calculated TDEE & BMR, weight change, data quality warnings

get_calorie_correlation

Analyze calorie intake vs weight change to estimate TDEE and BMR. Includes exercise calories and net intake breakdown.

Parameters: days (default: 30)

get_deficit_analysis

Calculate actual vs target calorie deficit, compare projected vs actual weight loss. Shows exercise contribution to total burn and estimated BMR.

Parameters: days (default: 30)

get_compliance_score

Track how often you hit calorie and protein targets. Shows compliance percentages and streaks.

Parameters: days, calorie_target, protein_target, tolerance

get_meal_patterns

Analyze meal timing patterns. Are you a breakfast skipper? Late night snacker?

Parameters: days (default: 30)

get_eating_window

Analyze intermittent fasting patterns including first/last meal times and eating window duration.

Parameters: days (default: 30)

get_day_of_week_patterns

Analyze nutrition and exercise patterns by day of week. Shows food intake, exercise calories, and net calories for each day.

Parameters: weeks (default: 4)

get_nutrition_comparison

Compare nutrition between two date ranges to spot trends (e.g., this week vs last week).

Parameters: start_date_a, end_date_a, start_date_b, end_date_b

get_food_frequency

Show how often specific foods appear in your log. Find your most frequently eaten foods.

Parameters: days, limit (default: 20)

get_top_meals

Get your highest calorie meals ever logged.

Parameters: limit (default: 10)

get_exercise_history

Get exercise history with totals and breakdown by exercise type.

Parameters: days (default: 30)

get_streaks

Get logging streak information including current and longest streaks.

Parameters: none

Body Composition Tools

Track body metrics from Apple Health including weight, body fat, and lean mass.

get_body_composition Apple Health

Get latest body composition metrics: weight, body fat %, lean body mass, and BMI.

Parameters: none

get_body_composition_history Apple Health

Get body composition history over time.

Parameters: days (default: 30)

get_body_composition_trend Apple Health

Analyze trends over time: weight change, body fat change, lean mass change.

Parameters: days (default: 30)

Vitals Tools

Monitor heart health, blood pressure, and cardiovascular fitness from Apple Health.

get_vitals Apple Health

Get latest health vitals: resting heart rate, HRV, blood pressure, VO2 max, SpO2.

Parameters: none

get_vitals_history Apple Health

Get daily vitals history over time.

Parameters: days (default: 30)

get_heart_rate_trend Apple Health

Analyze resting heart rate and HRV trends. Lower resting HR and higher HRV indicate better fitness.

Parameters: days (default: 30)

get_blood_pressure_history Apple Health

Get blood pressure readings over time with averages.

Parameters: days (default: 90)

get_vo2max_trend Apple Health

Analyze VO2 max cardio fitness trends. Higher values indicate better cardiovascular fitness.

Parameters: days (default: 30)

Activity & Sleep Tools

Track daily activity, sleep quality, mobility, and daylight exposure from Apple Health.

get_activity_history Apple Health

Get daily activity metrics: steps, distance, flights climbed, exercise minutes, active/basal calories.

Parameters: days (default: 30)

get_sleep_history Apple Health

Get sleep analysis data including duration, efficiency, and sleep stages (deep, core, REM).

Parameters: days (default: 30)

get_mobility_history Apple Health

Get movement quality metrics: walking speed, step length, asymmetry, steadiness, stair speed. Useful for injury prevention.

Parameters: days (default: 30)

get_daylight_history Apple Health

Get time spent in daylight. Important for circadian rhythm, mood, and SAD awareness.

Parameters: days (default: 30)

get_health_dashboard Apple Health

Get a comprehensive health dashboard with all key metrics: body composition, vitals, activity, sleep, mobility, and daylight exposure.

Parameters: none

Utility Tools

Tools for managing data refresh and cache.

refresh_database

Force refresh of the LoseIt database cache to get the latest data. The cache normally refreshes every 12 hours.

Parameters: none

refresh_apple_health Apple Health

Force refresh of the Apple Health data cache. Use after updating your export.xml file.

Parameters: none