# taxuspt/garmin_mcp architecture

> Architecture diagram of the GitHub repository taxuspt/garmin_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taxuspt/garmin_mcp
- Repository: https://github.com/taxuspt/garmin_mcp

## Overview

Garmin MCP is a tool server that lets an MCP-compatible client query and manage Garmin Connect fitness data. Its main workflow is client request → server tool registration and dispatch → domain-specific Garmin operations → formatted result returned to the client. The domain surface spans activities and analysis, health and training, and equipment, nutrition, and challenges; workout builders provide a higher-level creation and scheduling path. A separate authentication CLI can create saved Garmin tokens. The README documents additional tool coverage beyond the sampled excerpts, so those capabilities are represented at their documented module boundaries.

Main entry points: [`src/garmin_mcp/__init__.py`](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/__init__.py) (Server Entry), [`src/garmin_mcp/auth_cli.py`](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/auth_cli.py) (Auth CLI), [`src/garmin_mcp/workout_builders.py`](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/workout_builders.py) (Workout Builders), [`src/garmin_mcp/workouts.py`](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/workouts.py) (Workouts Plans)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP Server"]
  node_server_entry["Server Entry<br/>[__init__.py]"]
  node_tool_filter["Tool Filtering<br/>[__init__.py]"]
end

subgraph group_activity["Activity Tools"]
  node_activity_management["Activity Management"]
  node_activity_analysis["Activity Analysis"]
end

subgraph group_wellness["Health Training"]
  node_health["Health Wellness<br/>[health_wellness.py]"]
  node_training["Training Performance<br/>[training.py]"]
  node_weight["Weight Tracking"]
  node_womens_health["Women's Health<br/>[womens_health.py]"]
  node_nutrition["Nutrition<br/>[nutrition.py]"]
end

subgraph group_management["Plans Management"]
  node_workouts["Workouts Plans<br/>[workouts.py]"]
  node_workout_builders["Workout Builders"]
  node_workout_templates["Workout Templates"]
  node_calendar["Calendar Events<br/>[calendar_events.py]"]
  node_courses["Courses<br/>[courses.py]"]
  node_devices["Devices<br/>[devices.py]"]
  node_gear["Gear Management<br/>[gear_management.py]"]
  node_challenges["Challenges Badges<br/>[challenges.py]"]
  node_data_management["Data Management<br/>[data_management.py]"]
  node_user_profile["User Profile<br/>[user_profile.py]"]
end

subgraph group_auth["Authentication"]
  node_auth_cli["Auth CLI<br/>[auth_cli.py]"]
  node_token_utils["Token Utilities<br/>[token_utils.py]"]
end

node_client(("MCP Client"))
node_garmin_api["Garmin Connect"]
node_token_store[("Saved Tokens")]

node_client -->|"sends tool requests"| node_server_entry
node_server_entry -->|"filters registration"| node_tool_filter
node_server_entry -->|"registers tools"| node_activity_management
node_server_entry -->|"registers tools"| node_activity_analysis
node_server_entry -->|"registers tools"| node_health
node_server_entry -->|"registers tools"| node_training
node_server_entry -->|"registers tools"| node_weight
node_server_entry -->|"registers tools"| node_womens_health
node_server_entry -->|"registers tools"| node_nutrition
node_server_entry -->|"registers tools"| node_workouts
node_server_entry -->|"registers tools"| node_workout_builders
node_server_entry -->|"registers tools"| node_workout_templates
node_server_entry -->|"registers tools"| node_calendar
node_server_entry -->|"registers tools"| node_courses
node_server_entry -->|"registers tools"| node_devices
node_server_entry -->|"registers tools"| node_gear
node_server_entry -->|"registers tools"| node_challenges
node_server_entry -->|"registers tools"| node_data_management
node_server_entry -->|"registers tools"| node_user_profile
node_activity_management -->|"calls Garmin API"| node_garmin_api
node_activity_analysis -->|"retrieves activity files"| node_garmin_api
node_health -->|"calls Garmin API"| node_garmin_api
node_training -->|"calls Garmin API"| node_garmin_api
node_weight -->|"calls Garmin API"| node_garmin_api
node_womens_health -->|"calls Garmin API"| node_garmin_api
node_nutrition -->|"calls Garmin API"| node_garmin_api
node_workouts -->|"calls Garmin API"| node_garmin_api
node_workout_builders -->|"delegates uploads"| node_workouts
node_workout_builders -->|"schedules workouts"| node_garmin_api
node_workout_templates -->|"calls Garmin API"| node_garmin_api
node_calendar -->|"calls Garmin API"| node_garmin_api
node_courses -->|"calls Garmin API"| node_garmin_api
node_devices -->|"calls Garmin API"| node_garmin_api
node_gear -->|"calls Garmin API"| node_garmin_api
node_challenges -->|"calls Garmin API"| node_garmin_api
node_data_management -->|"calls Garmin API"| node_garmin_api
node_user_profile -->|"calls Garmin API"| node_garmin_api
node_auth_cli -->|"authenticates"| node_garmin_api
node_auth_cli -->|"uses token helpers"| node_token_utils
node_auth_cli -->|"writes tokens"| node_token_store
node_server_entry -->|"loads saved tokens"| node_token_store

click node_server_entry "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/__init__.py"
click node_tool_filter "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/__init__.py"
click node_activity_management "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/activity_management.py"
click node_activity_analysis "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/activity_analysis.py"
click node_health "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/health_wellness.py"
click node_training "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/training.py"
click node_weight "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/weight_management.py"
click node_womens_health "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/womens_health.py"
click node_nutrition "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/nutrition.py"
click node_workouts "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/workouts.py"
click node_workout_builders "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/workout_builders.py"
click node_workout_templates "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/workout_templates.py"
click node_calendar "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/calendar_events.py"
click node_courses "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/courses.py"
click node_devices "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/devices.py"
click node_gear "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/gear_management.py"
click node_challenges "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/challenges.py"
click node_data_management "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/data_management.py"
click node_user_profile "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/user_profile.py"
click node_auth_cli "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/auth_cli.py"
click node_token_utils "https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/token_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_entry,node_tool_filter,node_client toneBlue
class node_activity_management,node_activity_analysis,node_token_store toneAmber
class node_health,node_training,node_weight,node_womens_health,node_nutrition toneMint
class node_workouts,node_workout_builders,node_workout_templates,node_calendar,node_courses,node_devices,node_gear,node_challenges,node_data_management,node_user_profile toneRose
class node_auth_cli,node_token_utils,node_garmin_api toneIndigo
```

## Components

### MCP Server

- [Server Entry](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/__init__.py): `src/garmin_mcp/__init__.py`
- [Tool Filtering](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/__init__.py): `src/garmin_mcp/__init__.py`

### Activity Tools

- [Activity Management](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/activity_management.py): `src/garmin_mcp/activity_management.py`
- [Activity Analysis](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/activity_analysis.py): `src/garmin_mcp/activity_analysis.py`

### Health Training

- [Health Wellness](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/health_wellness.py): `src/garmin_mcp/health_wellness.py`
- [Training Performance](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/training.py): `src/garmin_mcp/training.py`
- [Weight Tracking](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/weight_management.py): `src/garmin_mcp/weight_management.py`
- [Women's Health](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/womens_health.py): `src/garmin_mcp/womens_health.py`
- [Nutrition](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/nutrition.py): `src/garmin_mcp/nutrition.py`

### Plans Management

- [Workouts Plans](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/workouts.py): `src/garmin_mcp/workouts.py`
- [Workout Builders](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/workout_builders.py): `src/garmin_mcp/workout_builders.py`
- [Workout Templates](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/workout_templates.py): `src/garmin_mcp/workout_templates.py`
- [Calendar Events](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/calendar_events.py): `src/garmin_mcp/calendar_events.py`
- [Courses](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/courses.py): `src/garmin_mcp/courses.py`
- [Devices](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/devices.py): `src/garmin_mcp/devices.py`
- [Gear Management](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/gear_management.py): `src/garmin_mcp/gear_management.py`
- [Challenges Badges](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/challenges.py): `src/garmin_mcp/challenges.py`
- [Data Management](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/data_management.py): `src/garmin_mcp/data_management.py`
- [User Profile](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/user_profile.py): `src/garmin_mcp/user_profile.py`

### Authentication

- [Auth CLI](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/auth_cli.py): `src/garmin_mcp/auth_cli.py`
- [Token Utilities](https://github.com/taxuspt/garmin_mcp/blob/main/src/garmin_mcp/token_utils.py): `src/garmin_mcp/token_utils.py`

### Other components

- **MCP Client**
- **Garmin Connect**
- **Saved Tokens**

## Connections

- MCP Client → Server Entry: sends tool requests
- Server Entry → Tool Filtering: filters registration
- Server Entry → Activity Management: registers tools
- Server Entry → Activity Analysis: registers tools
- Server Entry → Health Wellness: registers tools
- Server Entry → Training Performance: registers tools
- Server Entry → Weight Tracking: registers tools
- Server Entry → Women's Health: registers tools
- Server Entry → Nutrition: registers tools
- Server Entry → Workouts Plans: registers tools
- Server Entry → Workout Builders: registers tools
- Server Entry → Workout Templates: registers tools
- Server Entry → Calendar Events: registers tools
- Server Entry → Courses: registers tools
- Server Entry → Devices: registers tools
- Server Entry → Gear Management: registers tools
- Server Entry → Challenges Badges: registers tools
- Server Entry → Data Management: registers tools
- Server Entry → User Profile: registers tools
- Activity Management → Garmin Connect: calls Garmin API
- Activity Analysis → Garmin Connect: retrieves activity files
- Health Wellness → Garmin Connect: calls Garmin API
- Training Performance → Garmin Connect: calls Garmin API
- Weight Tracking → Garmin Connect: calls Garmin API
- Women's Health → Garmin Connect: calls Garmin API
- Nutrition → Garmin Connect: calls Garmin API
- Workouts Plans → Garmin Connect: calls Garmin API
- Workout Builders → Workouts Plans: delegates uploads
- Workout Builders → Garmin Connect: schedules workouts
- Workout Templates → Garmin Connect: calls Garmin API
- Calendar Events → Garmin Connect: calls Garmin API
- Courses → Garmin Connect: calls Garmin API
- Devices → Garmin Connect: calls Garmin API
- Gear Management → Garmin Connect: calls Garmin API
- Challenges Badges → Garmin Connect: calls Garmin API
- Data Management → Garmin Connect: calls Garmin API
- User Profile → Garmin Connect: calls Garmin API
- Auth CLI → Garmin Connect: authenticates
- Auth CLI → Token Utilities: uses token helpers
- Auth CLI → Saved Tokens: writes tokens
- Server Entry → Saved Tokens: loads saved tokens