Garmin Connect MCP Server

Languages: English | 日本語 (Japanese) | 简体中文 (Simplified Chinese)

A Model Context Protocol (MCP) server designed to retrieve daily health, fitness, and activity statistics from Garmin Connect and expose them to Large Language Models (LLMs). Built on Python's FastMCP, this server features robust authentication token persistence to protect your Garmin Connect account from being locked due to repeated login requests.

---

Features

• Token Session Persistence Cache: The Garmin Connect API frequently locks accounts if too many login requests are made in a short time. This server automatically caches your session tokens locally (defaults to ~/.garminconnect or configured path) upon the first successful login, reusing them for subsequent requests.
• 15 Rich Data Tools: Access steps, heart rate, sleep scores, stress, hydration, respiration, SpO2, body composition (weight/body fat), activity history, connected devices, and more.
• Strict Type Safety & Testing: Fully compliant with mypy --strict and ruff, with a comprehensive mock-based test suite.

---

Setup Instructions

Prerequisites

• Python 3.12 or higher
• uv (fast Python package and project manager)

1. Installation

Clone this repository and install it in editable mode:

git clone https://github.com/rmc8/rmc_garmin_mcp.git
cd rmc_garmin_mcp
uv pip install -e .

2. Environment Configuration

Copy .env.example to create a .env file and configure your Garmin credentials:

cp .env.example .env

Edit the .env file:

# Garmin Connect Login Email
GARMIN_EMAIL=your_email@example.com
# Garmin Connect Login Password
GARMIN_PASSWORD=your_password

# (Optional) Change the token directory path
# GARMINTOKENS=/path/to/tokens

3. Multi-Factor Authentication (MFA) Setup (Optional)

If your Garmin Connect account has MFA (Multi-Factor Authentication) enabled, you cannot log in directly from the MCP server as it runs in the background and cannot prompt for inputs.

Instead, run the interactive login helper command once in your terminal before launching the server:

uvx --with rmc-garmin-mcp rmc-garmin-login

(Or uv run rmc-garmin-login if you have cloned the source locally).

Enter your credentials and the MFA verification code. Once authentication is successful, the session tokens will be cached locally, and the MCP server will start up seamlessly in the background without prompting you again.

---

Running the Server

Via uvx (Recommended)

You can run the server directly without manual cloning or installation using uvx:

uvx rmc-garmin-mcp

Stdio Mode (From Local Source)

If you have cloned the repository locally, you can run the server using uv:

uv run rmc-garmin-mcp

Testing with MCP Inspector

You can test the exposed tools using the interactive MCP Inspector GUI:

npx @modelcontextprotocol/inspector uv run rmc-garmin-mcp

After executing, open the URL provided in your browser to run test executions of the tools.

---

MCP Client Configuration

To configure the server for MCP clients (such as Claude Desktop), add the following to your configuration file (e.g. claude_desktop_config.json):

Using uvx (Recommended)

This method executes the server directly from PyPI without requiring a local clone.

{
  "mcpServers": {
    "rmc-garmin-mcp": {
      "command": "uvx",
      "args": ["rmc-garmin-mcp"],
      "env": {
        "GARMIN_EMAIL": "your_email@example.com",
        "GARMIN_PASSWORD": "your_password"
      }
    }
  }
}

Using Local Source (via uv)

If you prefer to run the server from a cloned local repository, configure it like this:

{
  "mcpServers": {
    "rmc-garmin-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/rmc_garmin_mcp",
        "run",
        "rmc-garmin-mcp"
      ],
      "env": {
        "GARMIN_EMAIL": "your_email@example.com",
        "GARMIN_PASSWORD": "your_password"
      }
    }
  }
}

---

Exposed MCP Tools

Tool Name	Description	Key Arguments
get_steps_data	Fetch detailed step readings for a date.	cdate (YYYY-MM-DD)
get_heart_rates	Fetch heart rate data for a date.	cdate (YYYY-MM-DD)
get_daily_steps	Fetch summarized daily steps for a date range.	start, end (YYYY-MM-DD)
get_body_battery	Fetch Body Battery data for a date range.	start (req), end (opt)
get_hydration_data	Fetch hydration logs for a date.	cdate (YYYY-MM-DD)
get_last_activity	Fetch details of the most recent logged activity.	None
get_sleep_data	Fetch sleep scores and stages analysis for a date.	cdate (YYYY-MM-DD)
get_stress_data	Fetch detailed stress readings for a date.	cdate (YYYY-MM-DD)
get_all_day_stress	Fetch all-day stress records for a date.	cdate (YYYY-MM-DD)
get_user_summary	Fetch daily summary (steps, calories, resting HR).	cdate (YYYY-MM-DD)
get_respiration_data	Fetch respiration rates (breaths per minute) for a date.	cdate (YYYY-MM-DD)
get_spo2_data	Fetch SpO2 (blood oxygen) logs for a date.	cdate (YYYY-MM-DD)
get_body_composition	Fetch body composition (weight, body fat, muscle).	startdate (req), enddate (opt)
get_activities	List logged fitness activities with pagination.	start (offset), limit (count)
get_devices	List registered Garmin devices on the account.	None

---

Development and Verification

Code Formatting and Linting

uv run ruff format .
uv run ruff check . --fix

Type Checking (Mypy Strict)

uv run mypy src tests

Running Unit Tests (Pytest)

uv run pytest

Tests mock the Garmin Connect API to verify validator logic and tool execution behavior without hitting real endpoints.