athlete-ledger-mcp
Provides read-only MCP access to a locally synced athlete-ledger archive of Garmin Connect data, including activities and training metrics, activity totals by week/month/sport, daily sleep/HRV/stress wellness data, and ledger coverage/status information.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
athlete-ledger
Your training history, in a database you own, that any AI assistant can read.
Your watch records every session, every night of sleep, and every HRV reading. Getting a useful answer out of all that data is still hard. Dashboards show one chart at a time, and a general purpose AI assistant cannot see your data at all.
athlete-ledger closes that gap. It builds a faithful, local archive of your own training and wellness data, and serves it to AI assistants through the open Model Context Protocol (MCP). Then you can simply ask:
"Show my weekly training load and time in heart-rate zones for the last two months."
"How did I sleep, and what was my HRV, in the days after my longest rides?"
"Which weeks this autumn had the most vigorous intensity minutes, and how did my stress look in those weeks?"
The assistant calls a few small, read-only tools, gets back real numbers with explicit units, and answers from your data, not from guesses.
Goals
Official access, no password. The first data provider is Garmin Connect, through the official Personal API and Garmin's Python SDK. You use a personal API key; your account password is never involved.
A ledger you own. Data is synced incrementally into your own database: SQLite on your laptop, or Oracle Autonomous Database. Your history stays available offline and does not depend on API quotas or key expiry. Every provider response is kept as received, so new fields can be added later without downloading again.
Standard, read-only AI access. A standards-based MCP server exposes the ledger to any compatible assistant. Its tools only read, return data rather than opinions, and never contact the provider.
Privacy by design. It runs on your machine, with no telemetry. Logs and command output never contain your data, and sensitive fields (GPS, location names, identity) are never exposed.
Any endurance sport. Running, cycling, swimming, triathlon and more. The schema is ready for additional data providers.
Related MCP server: garmin-mcp
Status
Early development, but usable end to end: you can download your data, keep it current, and query it from an MCP client today. Versions are
0.0.x, nothing is published on PyPI yet, and interfaces and schema may still change.
Area | State | What works today |
Ledger store | β Working | SQLite and Oracle ADB (thin-mode mTLS), versioned migrations, least-privilege accounts |
Sync from Garmin Connect | β Working | Activities, sleep, HRV and stress summaries: backfill, incremental sync, coverage and gap detection, rebuild from stored responses |
Activity training metrics | β Working | Training effect and label, training load, TSS/IF/normalized power, elevation, max HR, speed, moving time, intensity minutes, time in HR zones |
MCP server over stdio | β Working | Four read-only tools with typed output schemas; verified on Oracle ADB with real data |
MCP over Streamable HTTP | π Next | Stateless transport (MCP 2026-07-28), bound to localhost |
Agent | π Planned | Small agent that uses the MCP tools, working with any OpenAI-compatible Responses API (for example OCI Generative AI or OpenAI) |
Chat UI | π Planned | Next.js chat that shows every tool call |
Packaging | π Planned | Published packages, container setup, documentation for a first release |
Out of scope for now: activity files (FIT) and intraday series, derived training-load analytics (CTL/ATL/TSB), writing back to Garmin, and multiple users.
How it works
Garmin Connect Personal API
β (official SDK, your personal API key)
βΌ
athlete-ledger sync βββΊ database you own (SQLite or Oracle ADB)
raw responses + normalized activity and daily tables
β read-only
βΌ
athlete-ledger-mcp βββΊ any MCP client
(desktop assistants, IDEs, MCP Inspector)Component | Command | Role |
Core |
| Database schema and migrations, provider access, sync |
MCP server |
| Read-only data tools over the ledger |
Agent |
| Planned; currently a placeholder |
The MCP tools are:
ledger_status: what has been downloaded, with gaps;list_activities: activities with all their metrics;activity_totals: totals by week, month or sport;daily_wellness: sleep, HRV and stress, day by day.
Documentation
Guide | Read it to... |
Go from zero to asking questions about your data, with SQLite | |
Configure SQLite or Oracle ADB, create and upgrade the schema | |
Provision Autonomous Database step by step | |
Download, keep current, find gaps, rebuild | |
Tools, units, client configuration, privacy | |
Environment, checks, layout and conventions | |
Rules and phase specifications for contributors and coding agents |
Privacy
Your data is health data, and athlete-ledger treats it that way. Everything runs locally, and
servers bind to 127.0.0.1. There is no telemetry, and logs never contain your values. The MCP
tools are read-only; on Oracle this is enforced by a database account that can only read.
When you connect an AI assistant, your questions and the tool results are sent to the model that assistant uses. Choose one whose data handling meets your requirements.
Disclaimer
athlete-ledger is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Garmin. Garmin and Garmin Connect are trademarks of Garmin Ltd. or its subsidiaries. Use of the Personal API is subject to Garmin's terms; it is intended for individuals accessing their own data.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
This server cannot be deployed
Maintenance
Related MCP Connectors
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Explore Garmin activity and health data with your AI assistant.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Garmin data in Claude: 135 tools β activities, sleep, HRV, training, workouts. Free, open source.
Related MCP Servers
- AlicenseBqualityBmaintenanceDownloads all your Garmin health and fitness data into a local SQLite database and exposes 45 MCP tools for AI analysis, enabling assistants to query sleep, training load, HRV, and more.4885 PyPI173AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server that exposes Garmin Connect health data from a local SQLite database to AI assistants, enabling queries for recent days, sleep, weekly trends, and a guarded SQL query surface.MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI assistants to retrieve and analyze Garmin Connect health data, including daily summaries, sleep, HRV, workouts, and raw FIT files, while also supporting SQL queries on the underlying database.10-
- AlicenseNot gradedqualityBmaintenanceSyncs your own Garmin Personal API data into a local SQLite archive and lets any MCP-capable AI assistant query sleep, HRV, stress, body battery, training and activity trends through natural language, with optional interactive charts. Everything runs locally with your own API key, so private health data stays on your machine.671 PyPI1Apache 2.0