Garmy 🏃‍♂️

An AI-powered Python library for Garmin Connect API designed specifically for health data analysis and AI agent integration. Build intelligent health assistants and data analysis tools with seamless access to Garmin's comprehensive fitness metrics.

Inspired by garth - This project was heavily inspired by the excellent garth library, building upon its foundation with enhanced modularity, type safety, and AI integration capabilities.

🎯 Key Features

🤖 AI-First Design: Built specifically for AI health agents and intelligent assistants
🏥 Health Analytics: Advanced data analysis capabilities for fitness and wellness insights
📊 Rich Metrics: Complete access to sleep, heart rate, stress, training readiness, and more
💾 Local Database: Built-in SQLite database for local health data storage and sync
🖥️ CLI Tools: Command-line interfaces for data synchronization and MCP server management
🤖 MCP Server: Model Context Protocol server for AI assistant integration (Claude Desktop)
⚡ High Performance: Optimized for high-performance AI applications
🛡️ Type Safe: Full type hints and runtime validation for reliable AI workflows
🔄 Auto-Discovery: Automatic metric registration and API endpoint discovery

📦 Installation

Standard Installation

pip install garmy

With Optional Features

# For local database functionality
pip install garmy[localdb]

# For MCP server functionality (AI assistants)
pip install garmy[mcp]

# For everything
pip install garmy[all]

Development Installation

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

🚀 Quick Start

Basic API Usage

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}")

Local Database & CLI Tools

# Sync recent health data to local database
garmy-sync sync --last-days 7

# Check sync status
garmy-sync status

# Start MCP server for AI assistants
garmy-mcp server --database health.db

# Show database info
garmy-mcp info --database health.db

# Get configuration examples
garmy-mcp config

AI Assistant Integration (Claude Desktop)

Add to your Claude Desktop configuration (~/.claude_desktop_config.json):

{
  "mcpServers": {
    "garmy-localdb": {
      "command": "garmy-mcp",
      "args": ["server", "--database", "/path/to/health.db", "--max-rows", "500"]
    }
  }
}

Now ask Claude: "What health data do I have available? Analyze my sleep patterns over the last month."

📊 Available Health Metrics

Garmy provides access to a comprehensive set of Garmin Connect metrics:

| Metric | Description | Example Usage | |--------|-------------|---------------| | sleep | Sleep tracking data including stages and scores | api_client.metrics.get('sleep').get() | | heart_rate | Daily heart rate statistics | api_client.metrics.get('heart_rate').get() | | stress | Stress level measurements | api_client.metrics.get('stress').get() | | steps | Daily step counts and goals | api_client.metrics.get('steps').list(days=7) | | training_readiness | Training readiness scores and factors | api_client.metrics.get('training_readiness').get() | | body_battery | Body battery energy levels | api_client.metrics.get('body_battery').get() | | activities | Activity summaries and details | api_client.metrics.get('activities').list(days=30) |

🧑‍💻 Architecture Overview

Garmy consists of three main modules:

🔌 Core Library

Garmin Connect API: Type-safe access to all health metrics
High Performance: Optimized concurrent operations
Auto-Discovery: Automatic endpoint and metric detection

💾 LocalDB Module

SQLite Storage: Local database for health data persistence
Data Sync: Robust synchronization with conflict resolution
CLI Tools: garmy-sync for data management

🤖 MCP Server Module

AI Integration: Model Context Protocol server for AI assistants
Secure Access: Read-only database access with query validation
Claude Desktop: Native integration with Claude Desktop
CLI Tools: garmy-mcp for server management

📚 Documentation

📖 Getting Started

Quick Start Guide - Get up and running in minutes
Basic Examples - Simple usage patterns

🏗️ Core Features

Available Metrics - All supported health metrics in this README

💾 Local Database

LocalDB Guide - Complete local storage guide
Database Schema - Schema and table structure

🤖 AI Integration

MCP Usage Example - Complete walkthrough from sync to AI analysis
MCP Server Guide - AI assistant integration
Claude Desktop Setup - Step-by-step Claude integration

🔬 Advanced Usage

Examples Directory - Comprehensive usage examples

🎯 Use Cases

For AI Developers

# Build AI health monitoring agents
from garmy import APIClient, AuthClient

def health_agent():
    auth_client = AuthClient()
    api_client = APIClient(auth_client=auth_client)
    
    # Login and get metrics
    auth_client.login(email, password)
    sleep_data = api_client.metrics.get('sleep').get()
    readiness_data = api_client.metrics.get('training_readiness').get()
    
    # AI analysis logic here
    return analyze_health_trends(sleep_data, readiness_data)

For Data Analysts

# Local database analysis workflow
garmy-sync sync --last-days 90  # Sync 3 months of data
garmy-mcp server --database health.db  # Start MCP server
# Use Claude Desktop or Python to analyze trends, correlations, patterns

For Health Researchers

# Large-scale health data collection
from garmy.localdb import SyncManager

sync_manager = SyncManager(db_path="research_data.db")
sync_manager.initialize(email, password)

# Collect comprehensive health dataset
stats = sync_manager.sync_range(
    user_id=1,
    start_date=date(2023, 1, 1),
    end_date=date.today(),
    metrics=[MetricType.SLEEP, MetricType.HRV, MetricType.STRESS]
)

🛡️ Security & Privacy

🔒 Local Data: All health data stored locally in SQLite
🔐 Read-Only MCP: AI assistants have read-only database access
🛡️ Query Validation: SQL injection prevention and query limits
🔑 Secure Auth: OAuth token management with automatic refresh
🚫 No Data Sharing: Health data never leaves your local environment

🧪 Examples

Check out the examples/ directory for comprehensive usage examples:

# Basic authentication and metrics
python examples/basic_usage.py

# Local database operations
python examples/localdb_demo.py

# MCP server configuration
python examples/mcp_server_example.py

# AI health analytics
python examples/ai_health_analytics.py

🔧 Development

Running Tests

# Install development dependencies
make install-dev

# Run all tests
make test

# Run specific test modules
make test-core      # Core functionality
make test-localdb   # LocalDB module
make test-mcp       # MCP server

# Check code quality
make lint
make quick-check

Adding Custom Metrics

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:
        return self.custom_field > 0

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/bes-dev/garmy.git
cd garmy
make install-dev
make ci  # Run quality checks

🙏 Acknowledgments

Garmy was heavily inspired by the excellent garth library by Matin Tamizi. We're grateful for the foundational work that made this project possible. Garmy builds upon garth's concepts with:

Enhanced modularity and extensibility
Full type safety with mypy compliance
Auto-discovery system for metrics
Local database integration
MCP server for AI assistants
Modern Python architecture and testing practices

Special thanks to the garth project and its contributors for pioneering accessible Garmin Connect API access.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

👨‍💻 Author

bes-dev - GitHub Profile

🔗 Links

Documentation - Complete documentation
PyPI Package - Install via pip
GitHub Issues - Bug reports and feature requests
Examples - Usage examples and tutorials

*Garmy mak

Garmy

Install / Use

README