With MCP Support (Recommended for AI Agents)

git clone https://github.com/bes-dev/garmy.git
cd garmy
pip install -e ".[dev,mcp]"

AI Agent Example (Recommended)

from garmy import AuthClient, APIClient
import asyncio

# Create an AI health agent
async def health_agent():
    auth_client = AuthClient()
    api_client = APIClient(auth_client=auth_client)
    
    # Login using environment variables (secure for AI agents)
    await auth_client.login_async(
        email=os.getenv('GARMIN_EMAIL'),
        password=os.getenv('GARMIN_PASSWORD')
    )
    
    # AI agent can now analyze multiple health metrics concurrently
    sleep_task = api_client.metrics.get('sleep').get_async()
    readiness_task = api_client.metrics.get('training_readiness').get_async()
    hrv_task = api_client.metrics.get('hrv').get_async()
    
    sleep_data, readiness_data, hrv_data = await asyncio.gather(
        sleep_task, readiness_task, hrv_task
    )
    
    # AI analysis logic here
    health_score = analyze_health_trends(sleep_data, readiness_data, hrv_data)
    return health_score

# Run AI health agent
health_insights = asyncio.run(health_agent())

from garmy import AuthClient, APIClient

# Create clients
auth_client = AuthClient()
api_client = APIClient(auth_client=auth_client)

# Login
auth_client.login("your_email@garmin.com", "your_password")

# Get today's training readiness
readiness = api_client.metrics.get('training_readiness').get()
print(f"Training Readiness Score: {readiness[0].score}/100")

# Get sleep data for specific date
sleep_data = api_client.metrics.get('sleep').get('2023-12-01')
print(f"Sleep Score: {sleep_data[0].overall_sleep_score}")

# Get multiple days of data
weekly_steps = api_client.metrics['steps'].list(days=7)

import asyncio
from garmy import AuthClient, APIClient

async def main():
    auth_client = AuthClient()
    api_client = APIClient(auth_client=auth_client)
    
    # Login
    await auth_client.login_async("your_email@garmin.com", "your_password")
    
    # Get multiple metrics concurrently
    sleep_task = api_client.metrics.get('sleep').get_async()
    hr_task = api_client.metrics.get('heart_rate').get_async()
    
    sleep_data, hr_data = await asyncio.gather(sleep_task, hr_task)

asyncio.run(main())

🤖 AI Health Agent Integration (MCP)

What Makes Garmy AI-First?

# Install Garmy with MCP support
pip install garmy[mcp]

# Verify installation
garmy-mcp --help

Option 1: Command Line Interface

# Start MCP server for Claude Desktop (STDIO transport)
garmy-mcp serve --transport stdio

# Start HTTP server for web clients
garmy-mcp serve --transport http --port 8080

# Show server information
garmy-mcp info

# List available metrics
garmy-mcp metrics

# Test server configuration
garmy-mcp test

Option 2: Programmatic Usage

from garmy.mcp import GarmyMCPServer, MCPConfig

# Create and configure server
config = MCPConfig.for_production()
server = GarmyMCPServer(config)

# Run server
server.run(transport="stdio")  # For Claude Desktop
server.run(transport="http", port=8080)  # For HTTP clients

Claude Desktop Configuration

Secure Setup (Recommended)

{
  "mcpServers": {
    "garmy": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "garmy.mcp", "serve", "--transport", "stdio"],
      "env": {
        "GARMIN_EMAIL": "your_email@example.com",
        "GARMIN_PASSWORD": "your_password",
        "GARMY_MCP_DEBUG": "false",
        "GARMY_MCP_CACHE_ENABLED": "true"
      }
    }
  }
}

Configuration File Locations

1. Environment Variables (Most Secure)

export GARMIN_EMAIL="your_email@example.com"
export GARMIN_PASSWORD="your_password"

2. Manual Input (Less Secure)

Intelligent Health Monitoring

Predictive Health Analytics

Conversational Health Queries

Smart Data Export & Visualization

MCP Configuration Options

from garmy.mcp.config import MCPConfig

# Development setup
config = MCPConfig.for_development()

# Production setup  
config = MCPConfig.for_production()

# Minimal setup
config = MCPConfig.minimal()

# Enable debug mode
export GARMY_MCP_DEBUG=true

# Run server with debug output
garmy-mcp serve --transport stdio --debug

📊 AI Health Data Analysis

Building AI Health Models

return insights” dir=”auto”>

from garmy import APIClient, AuthClient
import pandas as pd
import numpy as np
from sklearn.ensemble import RandomForestRegressor
from sklearn.preprocessing import StandardScaler

# Setup AI health analysis pipeline
auth_client = AuthClient()
api_client = APIClient(auth_client=auth_client)
auth_client.login("email", "password")

# Gather comprehensive health data for AI model
async def build_health_dataset(days=90):
    # Collect multiple health metrics concurrently
    tasks = [
        api_client.metrics.get('sleep').list_async(days=days),
        api_client.metrics.get('training_readiness').list_async(days=days),
        api_client.metrics.get('hrv').list_async(days=days),
        api_client.metrics.get('stress').list_async(days=days),
        api_client.metrics.get('body_battery').list_async(days=days)
    ]
    
    sleep_data, readiness_data, hrv_data, stress_data, battery_data = await asyncio.gather(*tasks)
    
    # Build comprehensive health dataset
    health_df = pd.DataFrame()
    # ... merge and process data for AI model training
    
    return health_df

# Train AI model to predict training readiness
def train_readiness_predictor(health_df):
    features = ['sleep_score', 'hrv_rmssd', 'stress_avg', 'body_battery_drained']
    X = health_df[features]
    y = health_df['training_readiness_score']
    
    model = RandomForestRegressor(n_estimators=100, random_state=42)
    model.fit(X, y)
    
    return model

# AI-powered health insights
def generate_health_insights(model, current_metrics):
    predicted_readiness = model.predict([current_metrics])[0]
    
    insights = {
        'readiness_prediction': predicted_readiness,
        'recommendation': 'high_intensity' if predicted_readiness > 75 else 'recovery',
        'confidence': model.score(X_test, y_test)
    }
    
    return insights

AI-Powered Health Monitoring

async def weekly_health_report(self):
“””Generate comprehensive AI health report”””
week_data = await self.api_client.metrics.get(‘daily_summary’).list_async(days=7)

# AI trend analysis
trends = self.analyze_trends(week_data)
predictions = self.predict_next_week(week_data)

return self.format_health_report(trends, predictions)

# Usage
agent = HealthMonitoringAgent(api_client)
daily_insights = await agent.daily_health_check()
weekly_report = await agent.weekly_health_report()” dir=”auto”>

# Create an AI health monitoring agent
class HealthMonitoringAgent:
    def __init__(self, api_client):
        self.api_client = api_client
        self.health_model = self.load_trained_model()
    
    async def daily_health_check(self):
        """Perform daily AI-powered health analysis"""
        # Get today's metrics
        today_data = await self.get_current_metrics()
        
        # AI analysis
        health_score = self.health_model.predict_health_score(today_data)
        recommendations = self.generate_recommendations(health_score, today_data)
        alerts = self.check_health_alerts(today_data)
        
        return {
            'health_score': health_score,
            'recommendations': recommendations,
            'alerts': alerts,
            'insights': self.generate_insights(today_data)
        }
    
    def generate_recommendations(self, health_score, data):
        """AI-generated personalized health recommendations"""
        if health_score > 80:
            return "Great day for high-intensity training!"
        elif health_score > 60:
            return "Moderate activity recommended. Focus on technique."
        else:
            return "Prioritize recovery today. Light movement only."
    
    async def weekly_health_report(self):
        """Generate comprehensive AI health report"""
        week_data = await self.api_client.metrics.get('daily_summary').list_async(days=7)
        
        # AI trend analysis
        trends = self.analyze_trends(week_data)
        predictions = self.predict_next_week(week_data)
        
        return self.format_health_report(trends, predictions)

# Usage
agent = HealthMonitoringAgent(api_client)
daily_insights = await agent.daily_health_check()
weekly_report = await agent.weekly_health_report()

# Basic authentication example
python examples/basic_auth.py

# Sleep analysis demo
python examples/sleep_demo.py

# Training readiness analysis
python examples/training_readiness_demo.py

# Comprehensive metrics sync
python examples/metrics_sync_demo.py

# MCP server demo
python examples/mcp_integration_demo.py

from dataclasses import dataclass
from garmy.core.base import BaseMetric

@dataclass
class CustomMetric(BaseMetric):
    endpoint_path = "/usersummary-service/stats/custom/{date}"

    custom_field: int
    timestamp: str
    
    def validate(self) -> bool:
        """Custom validation logic"""
        return self.custom_field > 0

from garmy.core.config import set_config, GarmyConfig

# Create custom configuration
config = GarmyConfig(
    request_timeout=30,
    retries=3,
    max_workers=10,
    default_user_agent="MyApp/1.0"
)

# Apply configuration
set_config(config)

# Or use environment variables
import os
os.environ['GARMY_REQUEST_TIMEOUT'] = '30'
os.environ['GARMY_MAX_WORKERS'] = '10'

# Install development dependencies
make install-dev

# Run all tests
make test

# Run specific test modules
make test-core      # Core functionality
make test-auth      # Authentication
make test-metrics   # Metrics
make test-mcp       # MCP server

# Check code quality
make lint
make quick-check

import asyncio
from garmy import APIClient, AuthClient

async def analyze_weekly_data():
    auth_client = AuthClient()
    api_client = APIClient(auth_client=auth_client)
    
    # Async login
    await auth_client.login_async("email", "password")
    
    # Fetch multiple metrics concurrently
    tasks = [
        api_client.metrics.get('sleep').list_async(days=7),
        api_client.metrics.get('steps').list_async(days=7),
        api_client.metrics.get('stress').list_async(days=7)
    ]
    
    sleep_data, steps_data, stress_data = await asyncio.gather(*tasks)
    
    return {
        'sleep': sleep_data,
        'steps': steps_data,
        'stress': stress_data
    }

# Run async analysis
data = asyncio.run(analyze_weekly_data())

from garmy.core.exceptions import APIError, AuthError, GarmyError

try:
    auth_client.login("wrong_email", "wrong_password")
except AuthError as e:
    print(f"Authentication failed: {e}")
except APIError as e:
    print(f"API error: {e}")
except GarmyError as e:
    print(f"General Garmy error: {e}")

from garmy.core.config import set_config, GarmyConfig

# Configure retry behavior