Garmin Local MCP

MCP数据服务

提供方 anup-shesh

数据服务 未标注 会话登录 社区 / 第三方 Claude DesktopClaudeCursorCodex
查看接入方式

Local-first Garmin data warehouse with an analysis-grade MCP server. Sync once, analyze forever - even when the API is down.

一句话选型结论

按资料字段整理

Garmin Local MCP 属于数据服务类 MCP 服务器,传输方式未标注,会话登录,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类数据服务 传输方式未标注 鉴权会话登录 部署方式未标注
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

数据服务
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

garmin fitness health sleep quantified self local first sqlite offline

支持客户端

适用场景

garminfitnesshealth

安装与配置

未标注 会话登录
上游未给出传输方式
garmin-local-mcp serve

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
数据库查询

用自然语言查库、取数,不用手写 SQL。

数据同步与清洗

把多来源数据拉到一处做整理。

报表取数

按口径快速拉出统计结果。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在数据服务场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Garmin Local MCP当前 未标注 未标注 未标注 有 未标注
Memory 9d25f64e 9 未标注 未标注 无 2026-05-17
Getzep MCP 9 stdio · 本地进程 本地部署 有 2026-05-17
anything-llm 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Prisma MCP Server 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Astr Bot 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

数据服务
字段来自项目仓库与公开索引,中文说明由本站标注
提供方anup-shesh上游标注的维护方 anup-shesh
分类数据服务本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · python本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

19.7 KB
来自项目仓库与上游目录的原文,未做删改

garmin-local-mcp

Local-first Garmin data warehouse with an analysis-grade MCP server.
Sync once, analyze forever, even when the API is down.

Try it without a Garmin account

If you don't own a Garmin, or just want to see what the tools return before
handing over credentials, seed a synthetic store:```
pip install garmin-local-mcp
garmin-local-mcp --data-dir ~/.garmin-mcp-demo demo
garmin-local-mcp --data-dir ~/.garmin-mcp-demo serve


That generates 180 days across every table, then serves them over MCP. No
login, no network, no account.

The data is generated rather than recorded, but it is not random. A latent
recovery factor drives HRV up while resting heart rate goes down, training
load raises the *next* day's resting heart rate, a six-day illness window sits
in the middle of the range, and a few sleep nights are deliberately missing.
Sleep timing carries a planted chronotype (MCTQ MSFsc 03:45, with alarm-pinned
work mornings and later, longer free nights), and the sleep score drops with
distance from that natural wake time. So the analysis tools have something real
to find. Over the full 180 days (exact figures shift a little with the end
date, because training days depend on the weekday):

| Ask | Returns |
|---|---|
| `correlate(hrv, resting_hr)` | −0.4 to −0.6, a genuine inverse relationship |
| `correlate(training_load, resting_hr, scan_lags=True)` | near 0 at lag 0, **+0.4 to +0.65 at lag 1** (90 to 100 training days, significant after correcting for the 15 lags scanned): the effect is next-day |
| `anomalies()` | the illness window, flagged across resting HR, HRV, skin temperature, sleep score and stress at once |
| `gaps()` | the missing sleep nights |
| `circadian()` | MSFsc within 10 minutes of the planted 03:45, a circadian wake around 07:45, and evidence `supportive` (the most that two holdout folds allow) |

The analysis tools default to the last 30 days, which misses the illness
window, so ask about the whole range (`demo` prints it). On a short window a
lag scan has little to work with; `correlate` says so in its `note` when the
strongest lag is not significant once all 15 lags are accounted for.

`sync_status` reports `demo_store: true` on these stores, so an assistant can
never present generated numbers as real measurements. The generator is
deterministic — `--seed` reproduces a store exactly, and `--days` changes the
range. `demo` refuses to overwrite a database it did not generate.

## Why another Garmin MCP?

Most Garmin MCP servers are thin live wrappers around Garmin's unofficial API.
Every question your AI assistant asks becomes one or more live API calls
returning large raw JSON blobs (a single raw sleep response runs around 230 KB),
which makes multi-month questions like "how does my sleep correlate with
training load?" expensive to ask.

That design is no longer universal. Since Garmin's auth change in March 2026
broke the ecosystem for several weeks, a number of projects have added local
storage, and the largest server computes training-load and HRV trends
server-side. Data ownership and server-side analysis are both crowded ground
now. Three things are not:

- **Sleep-timing advice that is tested before it is given.** `circadian`
  estimates your chronotype from your watch's sleep times (the Munich
  Chronotype Questionnaire's sleep-debt-corrected mid-sleep) and the wake time
  that fits it, with an 80% interval on each and a check of how much the answer
  moves under other reasonable settings. Then it asks whether waking near that
  time actually went with higher Garmin scores on nights the model never saw,
  beyond what sleep duration and schedule regularity explain, and says plainly
  when it didn't. Chronotype on its own is not new: other tools, including at
  least one MCP server, report MCTQ-style chronotype from wearable sleep data.
  I have not found another that puts uncertainty on the answer or validates it
  out of sample. See Sleep timing and chronotype.
- **Ingest that needs no login.** A standalone decoder for Garmin's undocumented
  wellness FIT messages (sleep score, HRV, skin temperature, sleep stages, naps)
  reads manually exported bundles with no credentials at all. Other servers
  parse FIT *activity* files; I have not found another that decodes the wellness
  export. It is the only ingest path here that keeps working when Garmin auth
  breaks.
- **Correlation with lag.** Pearson and Spearman between any two metrics with a
  scan over -7 to +7 day lags, so "training load raises my resting HR the next
  day" is a question with an answer.

The rest of the design follows from keeping your own copy:

- **Sync once, analyze forever.** Incremental sync into a local warehouse:
  immutable raw JSON snapshots plus a SQLite database, in a directory you own.
- **Compact responses.** Trends, correlations, baselines and anomaly detection
  are computed locally and returned as small columnar tables. Typical responses
  are under 2 KB (`circadian`, the richest, stays under 3 KB), so nothing floods
  the model's context.
- **Offline resilience.** An API breakage pauses new syncs only. Every query
  over already-synced history keeps working, and FIT import keeps filling gaps.
- **Curated tools.** 13 composable tools, not 110.

| | garmin-local-mcp | Most other Garmin MCPs |
|---|---|---|
| Zero-auth ingest path | Yes (wellness FIT bundle import) | No |
| Lag-aware correlation (-7 to +7 days) | Yes | No |
| Chronotype and wake-time advice, validated on unseen nights | Yes (intervals, stability check, rolling holdout) | A few report chronotype; none found that validate it |
| Response size discipline | Compact columnar tables, typically < 2 KB | Raw payloads; the largest server documents skipping its detail endpoint at 50-500 KB |
| Works offline after an API breakage | Yes, analysis plus FIT ingest | Varies; some keep a local cache |
| Local data store you own | Yes (raw JSON + SQLite) | Several now do this too |
| Tool count | 13 curated | 18 to 148 |

## Quickstart

Requires Python 3.12+.```
pip install garmin-local-mcp

Or run it without installing, via uv:```
uvx garmin-local-mcp --help


**1. Log in once** (MFA supported; tokens persist locally, so future runs never
ask for a password):```
garmin-local-mcp login

2. Backfill your history. The sync is resumable, safe to interrupt, and
throttled to be polite to Garmin's servers. A year of history is roughly 1,800
requests; for long backfills, start it and let it run (overnight works well).
If it gets rate limited or interrupted, re-run the same command and it resumes
where it left off.```
garmin-local-mcp sync --from 2026-01-01


**3. Register the MCP server with your client** (see Client setup
for Claude Desktop, Cursor, and other clients):```
claude mcp add --scope user garmin -- garmin-local-mcp serve

4. Ask questions. Examples of what Claude can now answer from your local
warehouse in one or two tool calls:

  • "How does my sleep score correlate with next-day resting HR?"
  • "What were my anomalous HRV days this quarter?"
  • "Show weekly training load vs sleep for the last 3 months."

Client setup

The server speaks stdio, so any MCP client works. pip install garmin-local-mcp
first (or use the uvx variants below, which need nothing installed beyond
uv).

Claude Code```
claude mcp add --scope user garmin -- garmin-local-mcp serve


**Claude Desktop, one-click:** download `garmin-local-mcp-x.y.z.mcpb` from the
latest release,
then in Claude Desktop open Settings > Extensions > Advanced settings, click
"Install Extension…", and select the file. Requires
uv on your PATH;
the extension installs and runs the server from PyPI via uvx, so no manual
Python setup is needed. If the install dialog warns about a missing
`Python >=3.12`, you can ignore it: uv provisions its own interpreter.

**Claude Desktop, manual** (Settings, then Developer, then Edit Config; add to
`claude_desktop_config.json`):```json
{
  "mcpServers": {
    "garmin": {
      "command": "garmin-local-mcp",
      "args": ["serve"]
    }
  }
}

Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project):```json
{
"mcpServers": {
"garmin": {
"command": "garmin-local-mcp",
"args": ["serve"]
}
}
}


**Any other stdio client / no local install** (requires uv):```json
{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["garmin-local-mcp", "serve"]
    }
  }
}

Note: login and the initial backfill sync are CLI steps (see
Quickstart); the MCP server itself never prompts for
credentials.

The 13 tools

Tool What it does
auth_status Check whether stored Garmin Connect tokens exist (use before sync, or after an auth error).
sync Fetch up to 60 days from Garmin Connect into the local store (default: last 30 days ending yesterday; big backfills belong in the CLI).
sync_status Local data coverage per table, last sync time, and pending sync errors.
get_day One merged view of a single day: wellness, sleep, HRV, training status, performance scores, activities, and data-quality flags.
query_metrics Columnar time series for one or more metrics between two dates, with daily/weekly/monthly aggregation and optional stats.
correlate Pearson/Spearman correlation between two metrics, with day-lag support and an optional scan over lags -7..+7.
baselines Personal mean +/- sd band per metric over a trailing window (default 28 days), to judge what is normal for this user.
anomalies Outlier days (z-score deviations) and sustained streaks (5+ consecutive days on one side of the mean).
list_activities Recent activities newest-first as a compact table, filterable by type, date range, and minimum distance.
get_activity Full stored summary row for one activity (summary fields only, no GPS or sample streams).
gaps Missing days per table plus unresolved sync errors, to find holes worth re-syncing before drawing conclusions.
import_fit Zero-auth offline ingest of a manually exported Garmin wellness FIT bundle.
circadian Chronotype (MCTQ), sleep need and an inferred wake window, each with an 80% interval, plus out-of-sample evidence on whether that window goes with higher Garmin scores. See Sleep timing and chronotype.

Only sync and import_fit write anything, and only inside the data
directory. The server never prompts: auth problems come back as structured
errors with a hint pointing at the login CLI.

Available metric names include resting_hr, sleep_score, hrv, steps,
stress_avg, body_battery_high, skin_temp_dev_c, vo2max, fitness_age,
achievable_fitness_age, training_load, endurance_score, hill_score,
readiness_score, race_5k_s, the sleep-timing metrics sleep_onset_min,
wake_time_min and mid_sleep_min (minutes from midnight of the wake date, so
a 23:00 bedtime is −60), and about 35 more; any tool given an unknown name
returns the full list.

Performance scores

Garmin's periodic fitness scores land in their own performance table:
endurance score, hill score (with its endurance and strength sub-scores),
training readiness (score, level, recovery time) and race predictions for 5k,
10k, half and full marathon (all in seconds).

These update on Garmin's own cadence rather than daily, so performance is
deliberately excluded from gaps — a day without a new endurance score is
normal, not a hole. Race predictions and hill score only move after qualifying
running activity, so long stretches of nulls are expected for anyone whose
training is mostly hiking, cycling or strength work.

Sleep timing and chronotype

circadian answers "when does my body clock want me to wake up?" from the sleep
start and end times already in the store. It returns three separate quantities,
each with an 80% interval from a week-block bootstrap:

  1. Chronotype (msf_sc). The Munich Chronotype Questionnaire measure:
    mid-sleep on free days, corrected for the extra sleep taken to repay workday
    debt. Labelled early (before 03:30), intermediate or late (after
    04:30); the bands are approximate and the number is the main value.
  2. Sleep need. Your mean free-night sleep window, unless you pass
    sleep_need_min. The range where your Garmin scores level off is reported
    alongside as a cross-check.
  3. Circadian-compatible wake window. msf_sc + sleep_need / 2. This is an
    inference, not an MCTQ output. With no catch-up sleep it is simply your
    average free-day wake time; with catch-up sleep it is that time moved
    earlier by half the catch-up.

It then checks the inference against what actually happened:

  • Stability. The estimate is recomputed over 90, 180 and 365 days, mean and
    median mid-sleep, and three travel-filter widths. stability: low usually
    means your schedule changed; pass a start after the change.
  • Evidence. On a rolling holdout (train 120 days, test the next 30), it
    compares a sleep-duration-only model with one that adds distance from your
    circadian wake, and controls for schedule regularity with a separate pair of
    models. The level is consistent, supportive, suggestive or
    unsupported. These describe how consistently the pattern held on unseen
    nights. They are not statistical significance, and evidence needs at
    least 180 days of history.
  • What it can't show. Readiness and sleep score are Garmin's own composite
    scores, not physiological measurements. The strongest possible conclusion is
    that waking near your window was associated with higher Garmin scores on
    nights the model never saw, beyond what sleep duration and regularity
    predict. It does not show that wake timing changes physiology.

When the formula and your past scores disagree by more than 30 minutes, the
tool keeps both and suggests a 21-night experiment between them rather than
averaging them away. Free days default to Saturday and Sunday mornings
(free_days changes that), and if you set alarms on free days the chronotype
comes out earlier than your body clock. Daylight-saving changes in the range
are listed, using the configured timezone or the host's. Shift workers
(daytime main sleep) get the rhythm and chronotype but no wake window.

Data layout and ownership

Everything lives in one directory you own (default ~/.garmin-mcp, override
with the GARMIN_MCP_DATA_DIR environment variable or --data-dir):```
~/.garmin-mcp/
├── config.toml # optional settings
├── tokens/ # Garmin Connect session tokens
├── raw/daily/YYYY/YYYY-MM-DD/<endpoint>.json # immutable raw API snapshots
├── raw/activities/<activity_id>.json # one snapshot per activity
└── garmin.db # SQLite warehouse


The raw JSON snapshots are the source of truth and are never overwritten. The
SQLite database is a derived, rebuildable index: `garmin-local-mcp reparse`
rebuilds it from the raw snapshots entirely offline, which is the universal
escape hatch for schema evolution and parser fixes. Your data never leaves
your machine.

## Data quality note

Garmin watches report a provisional on-device resting heart rate that can
diverge sharply from Garmin Connect&#x27;s finalized value on nights with sparse
sampling. A real observed case: the watch reported 69 bpm on-device while
Garmin Connect later finalized the same night at 56 bpm.

This project handles that in two ways:

- The API sync stores Garmin Connect&#x27;s finalized value.
- The FIT importer cross-checks the provisional on-device value against the
  overnight heart-rate floor. A resting HR sitting more than 10 bpm above the
  lowest overnight sample is a rate the watch never actually observed; it gets
  flagged (`rhr_far_above_hr_floor`) and withheld, leaving the field for the
  API to backfill rather than storing a misleading number.

Sparse sleep-stage logging is flagged the same way
(`sparse_sleep_stage_logging`), and flags surface in `get_day` so the analysis
layer knows which numbers to trust.

## Offline / fallback runbook

If Garmin breaks the unofficial API again (it has before):

1. **Everything analytical keeps working.** All query, correlation, baseline,
   anomaly, and gap tools run on your already-synced local history. Only new
   syncs pause.
2. **Keep ingesting without auth.** Download a daily FIT bundle from the
   Garmin Connect website and import it locally (exact steps below).
   `garmin-local-mcp import-fit ` decodes the bundle with zero
   authentication and fills the gap days. FIT-sourced rows never overwrite
   API-sourced rows (unless you pass `--force`).
3. **Resume when the community catches up.** Watch the
   python-garminconnect
   project for a fix, upgrade, and run `garmin-local-mcp sync` again. Thanks
   to resumable sync state, it picks up exactly where it stopped.

### Downloading a wellness bundle, step by step

1. Sign in at connect.garmin.com in any
   browser.
2. Go directly to
   ****
   (or click your avatar in the top-right corner, then **Settings**, then
   **Account Information** in the left sidebar).
3. Scroll to the bottom of the page, to the section titled
   **Export Wellness Data** (&quot;Download your wellness FIT files from a
   specific day. This includes data such as steps, sleep, stress, HRV and
   more.&quot;).
4. Pick a date in the **Date** field and click **Export**. Your browser
   downloads a small zip for that one day, containing roughly 12 to 15
   binary `.fit` files (`*_WELLNESS.fit`, `*_SLEEP_DATA.fit`,
   `*_HRV_STATUS.fit`, `*_SKIN_TEMP.fit`, `*_METRICS.fit`, and similar).
5. Unzip it into a folder and run:```
   garmin-local-mcp import-fit &quot;path/to/unzipped/folder&quot;
   ```

6. Repeat for each missing day (one bundle per date). The `gaps` tool or
   `garmin-local-mcp status` tells you which days need filling.

Two things worth knowing:

- **Overnight sleep belongs to the wake date.** To get last night&#x27;s sleep,
  export yesterday&#x27;s date if you slept into this morning, i.e. the date you
  woke up on.
- This per-day export is instant and separate from Garmin&#x27;s full account
  export (the &quot;Data Management&quot; link on the same page), which is a bulk
  archive that can take days to arrive by email and is not what
  `import-fit` expects.

## Configuration

Optional `config.toml` in the data directory:

| Key | Default | Meaning |
|---|---|---|
| `timezone` | system timezone | IANA name (e.g. `America/Denver`) used to compute &quot;yesterday&quot; for sync ranges |
| `units` | `metric` | `metric` or `statute` |
| `request_delay_seconds` | `1.0` | Delay between API requests during sync |
| `baseline_window_days` | `28` | Default trailing window for the `baselines` tool |

Environment variables:

| Variable | Meaning |
|---|---|
| `GARMIN_MCP_DATA_DIR` | Override the data directory (default `~/.garmin-mcp`) |
| `GARMINTOKENS` | Override the token store location (default `/tokens`) |
| `GARMIN_EMAIL` / `GARMIN_PASSWORD` | Optional, for non-interactive re-login; when set, `garmin-local-mcp login` skips the prompts (MFA may still prompt if your account requires it) |

## Development```
python -m venv .venv
.venv/bin/pip install -e .[dev]     # Windows: .venv\Scripts\pip install -e .[dev]
pytest
ruff check .

The test suite runs fully offline against sanitized JSON fixtures and small
FIT samples; CI never touches the live API.

Disclaimer

This project is not affiliated with, endorsed by, or supported by Garmin Ltd.
It uses the community python-garminconnect
library with your own credentials to access your own data. Garmin's APIs are
unofficial and can change or break at any time; when that happens, your synced
history remains fully usable and the FIT import path keeps working.

All data stays on your machine. Nothing phones home: no telemetry, no
third-party services, no cloud. Treat your data directory like the personal
health record it is, and never commit it to a repository.

License

MIT

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Garmin Local MCP 怎么安装?

在客户端按下面的安装命令接入:garmin-local-mcp serve。装完在客户端配置里引用同一个包或端点。

Garmin Local MCP 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Garmin Local MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Garmin Local MCP 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

Garmin Local MCP 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Garmin Local MCP 能提供哪些能力?

资料显示能力标签包括 garmin、fitness、health、sleep、quantified self、local first。具体工具清单以官方文档为准。

Garmin Local MCP 需要什么运行环境?

运行时为 python。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。