garmin-connect-personal-mcp

An MCP server that lets any AI assistant answer questions about your own Garmin data: sleep, HRV, stress, body battery, training and activities.

It syncs Garmin's official Personal API into a SQLite archive on your machine and serves it to Claude, ChatGPT, Gemini, Cursor, VS Code, Codex and any other MCP client.

Unofficial. This project is not affiliated with, endorsed by, or supported by Garmin. Garmin and Garmin Connect are trademarks of Garmin Ltd. or its subsidiaries.

Not medical advice. The data comes from consumer wearables. This server reports numbers and trends; it does not diagnose anything.

Status

Alpha. Syncing, the local archive and the stdio MCP server work and are tested on macOS, Linux and Windows. ChatGPT can connect through OpenAI Secure MCP Tunnel; see the ChatGPT guide. An optional Streamable HTTP mode is also available for self-hosted deployments.

Quickstart

You need uv and a Garmin Personal API key.

1. Install:

   uv tool install garmin-connect-personal-mcp
   

   To update later: uv tool upgrade garmin-connect-personal-mcp.

2. Save your key. Create one in Garmin Connect, then paste it at the hidden prompt:

   garmin-connect-personal-mcp init
   

3. Download your data (the last 90 days; later runs pick up where they left off):

   garmin-connect-personal-mcp sync --days-back 90
   

4. Keep it up to date (optional, recommended). Garmin's API won't fill in old days on request, so a daily sync keeps your history complete:

   garmin-connect-personal-mcp schedule install
   

5. Connect your assistant. Run it without --write first to see what it will change:

   garmin-connect-personal-mcp install-client claude-desktop --write
   

   Other clients: claude-code, cursor, vscode, gemini, codex. See docs/clients for each one.

   For ChatGPT, run the guided setup:

   garmin-connect-personal-mcp setup-chatgpt
   

   It checks prerequisites and configures a private Secure MCP Tunnel. OpenAI account/workspace setup is required; see the ChatGPT guide.

   On macOS, optional background startup keeps the tunnel running without an open terminal. Nothing is enabled automatically.

6. Ask: "How did I sleep last night?"

What you can ask

• "Summarize my training and recovery this week."
• "Is my resting heart rate lower than three months ago?"
• "Was last night's sleep normal for me?"
• "Did I sleep more in October than in September?"
• "On days I ran, was my sleep score higher?" (answered with read-only SQL)
• "How has my weekly running distance built up since July?"
• "Anything unusual in my HRV lately?"
• "Show me my sleep stages for the last two weeks."
• "Did my heart rate drift in the second half of yesterday's run?"

Ask to see your data ("show me my last 7 days of sleep") and apps that support MCP Apps (Claude Desktop, claude.ai, ChatGPT, VS Code) display an interactive chart. Elsewhere you get the same numbers as text.

The assistant uses eleven tools: garmin_describe_data, garmin_get_day, garmin_get_trend, garmin_get_baseline, garmin_compare_periods, garmin_list_activities, garmin_get_activity, garmin_get_activity_stream, garmin_query, garmin_show_chart and garmin_sync. See docs/tools.md for each tool and docs/data.md for what's stored, every metric and its unit, and what's never shared. Missing data is reported as missing, never as zero.

Troubleshooting

Run:

garmin-connect-personal-mcp doctor

It checks your API key, Garmin access, the local archive, recent sync errors and the daily schedule, and says how to fix anything wrong. The report contains no API key, health data or home folder path, so you can paste it into an issue as is. Add --offline to skip contacting Garmin.

Privacy

• You run it yourself, with your own key. There is no hosted service, and your data never passes through this project.
• Your archive and API key stay on your machine, outside this repository.
• The only network calls go to Garmin's own API, to sync. serve --read-only turns even that off.
• Tools never return your name, profile photos or GPS coordinates, even though Garmin's records contain them, so a cloud assistant isn't told where you live. The SQL tool, garmin_query, reads a cleaned copy that doesn't contain them either. Turn it off by leaving query out of --toolsets.

Development

uv sync
uv run pre-commit install
uv run pytest

AGENTS.md has the commands and repo rules, for people and AI coding agents alike. To report a security problem, see SECURITY.md.

License

Apache-2.0