# Garmin MCP (Model Context Protocol) Server

A Model Context Protocol server that provides seamless integration with Garmin Connect, allowing AI assistants to access your Garmin fitness and health data.

## Features

- **Activity Data**: Access recent activities, detailed workout information
- **Health Metrics**: Retrieve heart rate, sleep, and stress data
- **Daily Statistics**: Get daily activity summaries and statistics
- **Device Information**: Query connected Garmin device details
- **Date Range Queries**: Fetch historical data for specific time periods

## Prerequisites

- Python 3.8 or higher
- A Garmin Connect account
- MCP-compatible AI assistant (Claude Desktop, etc.)

## Installation

1. Clone this repository:
```bash
git clone https://github.com/hsavelli/Garmin-MCP.git
cd Garmin-MCP
```

2. Install dependencies:
```bash
pip install garminconnect mcp
```

Note: in some instances you might need to use the command pip3 instead. 


## Configuration

### For Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "garmin": {
      "command": "python", 
      "args": ["/path/to/garmin_mcp.py"]
    }
  }
}
```

Note: in some instances you might need to use the command python3 instead. 

## Usage

Once configured, the MCP server provides the following capabilities:

### Resources

The server exposes these Garmin data resources:
- `garmin://activities/recent` - Recent activities list
- `garmin://stats/daily` - Today's statistics
- `garmin://health/heart-rate` - Heart rate data
- `garmin://health/sleep` - Sleep tracking data
- `garmin://health/stress` - Stress level measurements
- `garmin://device/info` - Connected device information

### Tools

Available tools for interacting with Garmin Connect:

1. **authenticate_garmin** - Authenticate with your Garmin Connect account
   - Parameters: `email`, `password`

2. **get_activity_details** - Get detailed information about a specific activity
   - Parameters: `activity_id`

3. **get_stats_range** - Get statistics for a date range
   - Parameters: `start_date`, `end_date` (format: YYYY-MM-DD)

4. **sync_device** - Trigger device sync with Garmin Connect

### Example Interactions

In your AI assistant, you can:

```
"Authenticate with my Garmin account using email@example.com"
"Show me my recent activities"
"What was my heart rate data today?"
"Get my sleep data from last night"
"Show me my activity statistics for the past week"
```

## Security Notes

- Credentials are never stored by the MCP server
- Authentication is required for each session
- All data is fetched directly from Garmin Connect API
- No data is cached or persisted locally

## Development

### Project Structure

```
garmin_mcp.py    # Main MCP server implementation
README.md        # This file
```

### Adding New Features

To add new Garmin data endpoints:

1. Add a new resource in `list_resources()`
2. Implement the data fetching logic in `read_resource()`
3. Create a helper method for the specific data type
4. Optionally add a new tool in `list_tools()` for advanced functionality

## Troubleshooting

### Authentication Issues
- Ensure your Garmin Connect credentials are correct
- Check if you have 2FA enabled (may require app-specific password)
- Verify your account isn't locked due to too many attempts

### Connection Errors
- Check your internet connection
- Garmin Connect may be temporarily unavailable
- Rate limiting may apply for excessive requests

### MCP Connection Issues
- Verify the path to `garmin_mcp.py` in your configuration
- Ensure Python is in your system PATH
- Check MCP server logs for detailed error messages

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

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

## Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Garmin Ltd. or its subsidiaries. It uses the unofficial garminconnect Python library to interact with Garmin Connect services.

## Acknowledgments

- [garminconnect](https://github.com/cyberjunky/python-garminconnect) - Python library for Garmin Connect
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification and SDK