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.

Related MCP server: Garmin Multi-Account MCP

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

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.