Garmin Connect

The Garmin Connect MCP Server lets you connect to Garmin Connect and expose your fitness and health data to MCP-compatible clients. You can access activities, health metrics, devices, training data, and more through a standardized MCP interface, enabling workflows with clients like Claude Desktop or the MCP Inspector.

How to use

You will run the Garmin Connect MCP Server as a local process and connect an MCP client to it. Use a local stdio configuration to start the server, then load it in your MCP client to access activities, health data, training information, devices, and other Garmin Connect data. Start by ensuring your credentials are configured so the server can authenticate with Garmin Connect. Once running, you can query for recent activities, steps, heart rate, sleep, body composition, and other supported data through the MCP client’s prompts.

How to install

Prerequisites you need installed on your system before setting up the Garmin Connect MCP Server:

• Python 3.7+

• A Garmin Connect account with 2FA enabled

Installation steps

# 1. Clone the project repository
# (Replace with the actual repository URL)
git clone <repository-url>
cd garmin_mcp

# 2. Create and activate a Python virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

Configure environment variables

# Garmin Connect credentials
GARMIN_EMAIL=your.email@example.com
GARMIN_PASSWORD=your-password

# MFA / 2FA options (choose one)
GARMIN_MFA_CODE=123456
# GARMIN_MFA_WEBHOOK=https://api.example.com/mfa

# Email-based MFA (automatic)
EMAIL_USER=your.email@gmail.com
EMAIL_PASSWORD=your-app-password
EMAIL_SERVER=imap.gmail.com
EMAIL_PORT=993

# Optional notifications
NTFY_SERVER=https://ntfy.sh
NTFY_TOPIC=garmin-notifications
NTFY_TOKEN=your-ntfy-token

# Token storage (optional)
GARMINTOKENS=~/.garminconnect
GARMINTOKENS_BASE64=~/.garminconnect_base64

Start the server with a pre-configured MCP client (example)

Use a local stdio configuration to run the MCP server from your MCP client environment. An example client configuration embeds the runtime path to a Python virtual environment and the server script to execute.

# Example from a local client configuration (absolute paths required)
{
  "mcpServers": {
    "garmin_connect": {
      "command": "/full/path/to/garmin_mcp/venv/bin/python",
      "args": [
        "/full/path/to/garmin_mcp/garmin_mcp_server_fixed.py"
      ],
      "env": {
        "GARMIN_EMAIL": "your.email@example.com",
        "GARMIN_PASSWORD": "your-password",
        "EMAIL_USER": "your.email@gmail.com",
        "GOOGLE_CLIENT_SECRET_FILE": "/path/to/client_secret.json",
        "GMAIL_TOKEN_FILE": "~/.gmail_token.json",
        "NTFY_SERVER": "https://ntfy.sh",
        "NTFY_TOPIC": "garmin-notifications",
        "NTFY_TOKEN": "your-ntfy-token"
      }
    }
  }
}

Security and authentication

The server implements headless authentication with multiple MFA strategies and automatic token management. It can automatically refresh tokens, perform checks before authentication, and log authentication attempts. Real-time notifications can be sent via ntfy for authentication events, rate-limiting events, and status changes.

Running the server in tests and production

To verify functionality during development, run the inspector test to confirm the Garmin MCP server tools are exposed. Use the inspector to ensure the garmin_status tool is available when authentication has not yet completed.

npx @modelcontextprotocol/inspector python garmin_mcp_server_fixed.py
# Shows: garmin_status tool available

Troubleshooting

Authentication issues often relate to MFA delivery or token validity. If you encounter a rate-limit error, wait briefly and retry. Review authentication logs to diagnose failures and ensure your tokens are valid.

Notes on usage with Claude Desktop

If you use Claude Desktop, configure the MCP server entry to point at your local Python runtime and the server script. The client will handle initiating authentication and maintaining the connection, allowing you to query Garmin Connect data through Claude’s interface.

Summary of data you can access

You can retrieve activities, health metrics (steps, heart rate, sleep, stress, body battery), body composition (weight, BMI, body fat, muscle mass), user profile data, device information, training data, and related Garmin Connect resources through the MCP interface.

Security considerations

Do not commit your .env or credentials to version control. Use environment variables for production deployments, rotate MFA codes regularly, monitor authentication logs, and consider webhook-based authentication for automated systems.

Notes on upgrades and maintenance

Monitor authentication status, apply rate-limit handling, and verify full functionality after any credential changes. Run full verification with the inspector to ensure all Garmin Connect tools are exposed.

Available tools

list_activities

List recent activities available from Garmin Connect via MCP

get_activity_details

Retrieve detailed information for a specific activity by ID

get_steps

Query daily step counts for a given date range

get_heart_rate

Fetch heart rate data for a specified date

get_sleep_data

Access sleep data for a given date or range

list_devices

List connected Garmin devices and their status

get_training_plan

Retrieve the current training plan and workouts

get_body_composition

Obtain body composition metrics such as weight, BMI, body fat, and muscle mass