Garmin MCP工具

Remove the volume (will require re-authentication)

docker volume rm garmin_mcp_garmin-tokens ```

Using with Claude Desktop via Docker

To use the Dockerized MCP server with Claude Desktop, you can configure it to communicate with the container. However, note that MCP servers typically communicate via stdio, which works best with direct process execution. For Docker-based deployments, consider using the standard uvx method shown in the With Claude Desktop section instead.

Run end-to-end tests (requires real Garmin credentials)

uv run pytest tests/e2e/ -m e2e -v ```

One-click Install (Claude Desktop)

The easiest way to add this server to Claude Desktop is via the .dxt Desktop Extension file — no JSON editing required.

Download and install

1. Download the latest garmin-mcp.dxt from the Releases page.
2. Drag the .dxt file into the Claude Desktop window, or double-click it, or go to Settings → Extensions → Install Extension and select the file.
3. Claude Desktop will prompt you for optional configuration (token path, email, password).

Build the `.dxt` yourself

bash scripts/build_dxt.sh   # produces garmin-mcp.dxt in the repo root

---

Setup

Install and run authentication tool

uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp-auth

Development Setup

1. Install the required packages on a new environment:

uv sync

With Docker

Docker provides an isolated and consistent environment for running the MCP server.

Quick Start with Docker Compose (Recommended)

1. Create a .env file with your credentials:

echo "GARMIN_EMAIL=your_email@example.com" > .env
echo "GARMIN_PASSWORD=your_password" >> .env

1. Start the container:

docker compose up -d

1. View logs to monitor the server:

docker compose logs -f garmin-mcp

Using Docker Directly

```bash

Build the image

docker build -t garmin-mcp .

Reinstalling from local path

If you are working from a local checkout or fork:

uv tool install --python 3.12 --force C:\Users\aresd\Desktop\programacion\garmin_mcp

Full flow example

create_walk_run_workout(name="W3 Mié 2:2", run_seconds=120, walk_seconds=120,
                        repeats=9, warmup_min=10, cooldown_min=8)
  → workout_id = 1560092011

schedule_workout(workout_id=1560092011, date="2026-05-06")
  → OK

After syncing your watch, the workout appears on the Forerunner 965 calendar.

Quick Start for MCP Clients

The easiest way to use this MCP server with Claude Desktop, Codex, or another MCP client is to authenticate once before adding the server to your configuration.

Prerequisites

• Python 3.12+
• Garmin Connect account
• MFA may be required if enabled on your account

Step 1: Pre-authenticate (One-time)

Before adding the server to your MCP client, authenticate once in your terminal:

```bash

Usage Examples

Once connected in Claude, you can ask questions like:

• "Show me my recent activities"
• "What was my sleep like last night?"
• "How many steps did I take yesterday?"
• "Show me the details of my latest run"
• "Analyze my last ride's power zones and compare to my training zones"
• "Show me my CTL, ATL, and TSB trend for the last 6 weeks"
• "What was my power duration curve from yesterday's ride? Estimate my FTP."
• "Analyze the FIT data from my last cycling activity — how was my shifting quality on the climbs?"
• "Show me my HRV trend for the last 2 weeks and flag any recovery concerns"
• "What's my season best 20-minute power and when did I set it?"

- Email (or set GARMIN_EMAIL env var)

- Password (or set GARMIN_PASSWORD env var)

Configuration

Your Garmin Connect credentials are read from environment variables:

• GARMIN_EMAIL: Your Garmin Connect email address
• GARMIN_EMAIL_FILE: Path to a file containing your Garmin Connect email address
• GARMIN_PASSWORD: Your Garmin Connect password
• GARMIN_PASSWORD_FILE: Path to a file containing your Garmin Connect password
• GARMIN_IS_CN: Set to true to use Garmin Connect China (garmin.cn) instead of the international version (default: false)

File-based secrets are useful in certain environments, such as inside a Docker container. Note that you cannot set both GARMIN_EMAIL and GARMIN_EMAIL_FILE, similarly you cannot set both GARMIN_PASSWORD and GARMIN_PASSWORD_FILE.

Use environment variables for credentials

GARMIN_EMAIL=you@example.com GARMIN_PASSWORD=secret garmin-mcp-auth

Now add to Claude Desktop config without credentials

After initial authentication, configure Claude Desktop **without** credentials (tokens are already saved):

#### Using Docker with MFA

If using Docker, follow the [Handling MFA with Docker](#handling-mfa-with-docker) section above for a streamlined experience with persistent token storage.

#### Troubleshooting MFA

**Error: "MFA authentication required but no interactive terminal available"**

Solution:
1. Open terminal
2. Run: `garmin-mcp-auth`
3. Enter credentials and MFA code
4. Restart Claude Desktop

**Token Expired**

OAuth tokens expire periodically (approximately every 6 months). Re-authenticate:

**Verify Tokens Work**

Intentionally Skipped Endpoints

Some endpoints are not implemented due to performance or complexity considerations:

High Data Volume: - get_activity_details() - Returns large GPS tracks and chart data (50KB-500KB). Use get_activity() for summaries instead.

Specialized Workout Formats: - upload_running_workout(), upload_cycling_workout(), upload_swimming_workout() - Sport-specific workout uploads. Use upload_workout() for general workouts.

Maintenance & Destructive Operations: - delete_activity(), delete_blood_pressure() - Destructive operations require careful consideration. - Internal/Auth methods: login(), resume_login(), connectapi(), download() - Handled automatically by the library.

If you need any of these endpoints, please open an issue.

Or use the CLI flag

garmin-mcp-auth --is-cn

For Claude Desktop, add `GARMIN_IS_CN` to the `env` section:

For Docker, add GARMIN_IS_CN=true to your .env file or uncomment it in docker-compose.yml.

Run all integration tests (default - uses mocked Garmin API)

uv run pytest tests/integration/

Run a specific test module

uv run pytest tests/integration/test_health_wellness_tools.py -v

Troubleshooting