Fitro MCP
Your fitness and wellness data, available to an MCP-compatible assistant through five focused tools: Activity, Health (including women's health), Wellness, Profile, and Discover. Uses the official Garmin Connect Personal API, with all 28 reviewed read-only operations available through progressive discovery.
Version 1.0.0 · Python 3.11–3.14 · MIT · Local stdio MCP
Try a simple prompt
After connecting Fitro to Codex, ask:
Use Fitro to show my steps and sleep for yesterday. Discover the operations you need first, and tell me if any data is unavailable.
For a connection check that does not request personal health data:
Use Fitro to list the available activity types.
Other examples: “Find my five most recent running activities,” or “Compare my sleep over the last seven days.” Fitro retrieves data; your assistant writes the explanation. Missing measurements should be reported as unavailable.
Install
You need Python 3.11+, uv, and a Garmin Connect Personal API key. A Garmin login/password alone is not enough. Create your key using the official Personal API key setup page. Sign in to Garmin Connect, open Personal API Key, select Create Key, accept the terms, choose an expiry and save the key when it is shown. Fitro exchanges that key for a bearer token automatically.
Run the versioned PyPI package without managing an environment:
uvx fitro-mcp@1.0.0 --version
Or install with pip inside a virtual environment:
python -m venv .venv
source .venv/bin/activate
python -m pip install fitro-mcp==1.0.0
fitro-mcp --version
Fitro runs as an MCP stdio process. Starting it without a client waits for protocol messages on stdin; it does not open a web page or interactive shell. Linux is tested. macOS uses the same POSIX file-permission model but has not been tested locally. Native Windows is not supported in 1.0.0; use WSL for a Linux environment.
Add to Codex
Add this block to ~/.codex/config.toml (or edit an existing fitro entry):
[mcp_servers.fitro]
command = "uvx"
args = ["fitro-mcp@1.0.0"]
startup_timeout_sec = 60
[mcp_servers.fitro.env]
GARMIN_PERSONAL_API_KEY = "PASTE_YOUR_PERSONAL_API_KEY_HERE"
Replace the placeholder locally. Keep the key out of chat and source control.
Global is the default region. For China-region accounts, add
FITRO_REGION = "china" under the environment table. For debug logging, use
args = ["fitro-mcp@1.0.0", "--debug"].
Alternatively, register a placeholder with the Codex CLI, then edit the key in the configuration file:
codex mcp add fitro --env GARMIN_PERSONAL_API_KEY=PASTE_YOUR_PERSONAL_API_KEY_HERE -- uvx fitro-mcp@1.0.0
codex mcp list
If your Codex launcher supplies the key from its environment, use the following
instead of the [mcp_servers.fitro.env] table:
# Inside [mcp_servers.fitro]
env_vars = ["GARMIN_PERSONAL_API_KEY"]
Do not configure both approaches with a placeholder that overrides the real key.
If uvx is not on your launcher's PATH, set command to its absolute path. Allow
extra startup time for the initial package download. Restart Codex or reconnect its
MCP server after changing configuration; verify Fitro is connected, then try the
prompt above. See the official Codex MCP guide.
Run from this checkout
uv sync --locked
uv run fitro-mcp --version
For Codex, replace the PyPI entry's command and arguments with:
[mcp_servers.fitro]
command = "uv"
args = ["--directory", "/absolute/path/to/gc-gather-mcp", "run", "--locked", "fitro-mcp"]
startup_timeout_sec = 60
[mcp_servers.fitro.env]
GARMIN_PERSONAL_API_KEY = "PASTE_YOUR_PERSONAL_API_KEY_HERE"
A direct local run can take the key from your shell. Bash example:
read -rsp 'Personal API key: ' GARMIN_PERSONAL_API_KEY; echo
export GARMIN_PERSONAL_API_KEY
uv run fitro-mcp
No .env file is loaded automatically. Keys are never accepted as command-line
arguments. Store client configuration with user-only permissions, such as 0600
on POSIX systems.
Other MCP clients
Clients using the mcpServers JSON format can use:
{
"mcpServers": {
"fitro": {
"command": "uvx",
"args": ["fitro-mcp@1.0.0"],
"env": {"GARMIN_PERSONAL_API_KEY": "PASTE_YOUR_PERSONAL_API_KEY_HERE"}
}
}
}
What Fitro provides
- Five domain/discovery tools with about 77% smaller advertised definitions than the original 28-tool interface (serialized JSON size, not a model token benchmark).
- Offline documentation resources, URI templates and resource argument completion.
- Validated input schemas, bounded responses, explicit pagination and structured errors.
- API-key exchange for a bearer token, memory-only caching and one renewal after a 401.
- Private rotating diagnostics with
--debug; stdout is reserved for MCP. - Typed modular Python code, uv lockfile, Ruff security rules, strict mypy, synthetic tests, dependency auditing, package smoke checks and CI.
Live token exchange and activity-types retrieval have been verified on the global region. Individual health endpoints and China-region authentication are not fully verified live. See authentication and verification for the precise scope.
Independent project. Not affiliated with, endorsed by, or sponsored by Garmin. Garmin and Garmin Connect are trademarks of Garmin Ltd. or its subsidiaries. The Personal API FAQ limits the Personal API to an individual's own data and excludes commercial applications serving multiple users. Installing this MIT-licensed client does not grant rights to upstream services. The Fitro name has not received trademark clearance.
Domain tools and discovery
Only five tools appear in tools/list. API endpoints are internal operations,
not separate tools:
| Tool | Operations |
|---|---|
activity |
activity_types, activity, activity_workouts, search_activities, download_activity, wellness_activity_range |
health |
heart_rate, heart_rate_zones, hrv, hrv_range, vo2_max_range, fitness_age, spo2, weight_measurements, weight_range, weight_goals, menstrual_cycle_summary, menstrual_cycle_day |
wellness |
daily_summary, daily_summaries, steps_range, stress_range, hydration_range, body_battery, sleep, sleep_range, food_logs |
profile |
user_settings |
discover |
Offline domain browsing, operation search, and exact schemas/examples |
Women's health is included in health. Each execution tool accepts operation
and parameters, enforces its domain boundary, and validates the exact operation
schema before any authentication or data request.
An assistant can progressively discover the operation it needs:
-
discover({})returns the four domains and operation counts. -
discover({"domain": "wellness"})returns a short operation page. -
discover({"domain": "wellness", "operation": "sleep_range"})returns the exact parameter schema, a synthetic example, and its documentation URI. -
wellnessexecutes the operation:{ "operation": "sleep_range", "parameters": { "startDate": "2026-11-01", "endDate": "2026-11-07" } }
discover also accepts query (up to 200 characters), limit (1–10, default 8),
and offset for subsequent pages. It returns total and next_offset; it never
loads all parameter schemas at once. For example, {"query": "women"} finds the
two cycle operations. Discovery is a local keyword search, not another model call.
Known operation contracts can be executed directly without repeating discovery.
All tools return a structured envelope with request_id and data. Failures set
isError and include a safe error.code and error.message. Query data contains
operation and result; discovery data contains catalog metadata. A JSON text
fallback carries the same envelope for clients without structured-result support.
Arguments inside parameters preserve Swagger names, including activityId,
calendarDate, startDate, and endDate. Dates use YYYY-MM-DD. Optional
arguments are omitted upstream unless supplied; Swagger defaults are informational.
Activity search accepts limit 1–1000 and a nonnegative start. There is no
automatic data pagination: advance start explicitly. Data is not silently truncated;
responses exceeding the configured cap fail with a safe error. Request small ranges.
Activity downloads return result containing media_type, encoding: "base64",
and data. They are never written to disk. Base64 increases output size; large
files may exceed server or client limits. No arbitrary HTTP or filesystem tools
are exposed.
MCP resources and completion
The server advertises a guide and four domain resources through resources/list:
fitro://guidefitro://domains/{domain}fitro://operations/{domain}/{operation}
The last two are also resource templates. Domain resources list all operations
in that domain, while an operation resource supplies its exact schema and example.
completion/complete suggests domain names and domain-scoped operation names for
these resource templates. All resource reads and completion requests work offline.
Resources and tools use the same catalog. The discover tool provides the same
information for clients that do not expose resources to their model. Server
instructions explain this workflow during initialization. Prompt workflows and
dynamic tool activation are not part of this interface.
Migration: the original 28 endpoint tool names are no longer registered. For
example, replace get_hrv({"calendarDate": "2026-11-20"}) with
health({"operation": "hrv", "parameters": {"calendarDate": "2026-11-20"}}).
Configuration
| Variable | Default | Purpose |
|---|---|---|
GARMIN_PERSONAL_API_KEY |
required | Personal API credential |
FITRO_REGION |
global |
global (.com) or china (.cn) |
FITRO_TIMEOUT_SECONDS |
30 |
HTTP timeout per network phase, 1–120 seconds |
FITRO_MAX_RESPONSE_BYTES |
8388608 |
Decoded response cap, 1 KiB–32 MiB |
No .env files are auto-loaded. TLS verification is enabled; redirects and
HTTPX environment proxy configuration are disabled. Only official regional hosts
are reachable through the public configuration. Health data returned by a tool is
visible to your MCP client and potentially its model provider: choose a trusted
client and configure its data handling accordingly.
A 401 triggers one token renewal, then a safe authentication error. A 403 indicates permissions, 404 missing data, and 429 a rate limit; wait before retrying. Other HTTP and network failures produce sanitized errors. No automatic retries are made for rate limits or server errors. Narrow date ranges if responses exceed the cap.
Private diagnostics
The region defaults to global. For debugging, append --debug after the server
command in your MCP client configuration:
{
"mcpServers": {
"fitro": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/gc-gather-mcp", "run", "--locked", "fitro-mcp", "--debug"],
"env": {
"GARMIN_PERSONAL_API_KEY": "YOUR_PERSONAL_API_KEY"
}
}
}
}
The PyPI equivalent is "command": "uvx" with
"args": ["fitro-mcp", "--debug"]. There is no log-level environment setting.
Logs go to ~/.starbridge/fitro.log, using the requested .starbridge
directory spelling. The active file rotates before reaching 1,000,000 bytes;
three backups (fitro.log.1 through .3) are retained. Each file is at most
1 MB, for approximately 4 MB total. An additional private lock file coordinates
rotation across simultaneous clients. Default verbosity is warnings/errors; --debug
adds fixed diagnostic events. On POSIX systems the directory is 0700 and files
are 0600; pre-existing symlinks and hard-linked files are refused.
Logs contain only timestamps, severity, fixed generic event names, random diagnostic request IDs, HTTP status codes and durations. No health payloads, parameter values, queried dates, activity IDs, domain/operation names, URLs, headers, keys, tokens or exception text are logged. Third-party SDK/HTTP log output is excluded. Diagnostics remain local and are not forwarded as MCP logging notifications. stdout remains MCP-only; a logging initialization/write failure reports a fixed message on stderr.
Match a failed tool result's request_id to the local log when troubleshooting.
Debug output deliberately cannot show upstream response bodies or detailed payloads.
Develop and verify
uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest
uv run pip-audit
uv build
uv run twine check dist/*
Tests never need an API key or live account. See AGENTS.md for the repo map and definition of done, architecture for extension points, and publishing for release steps. See verification results for the checks run.
Source: official Swagger page. The bundled catalog contains reviewed operation metadata, not a runtime dependency on the documentation website. API responses are returned as provided, with no medical interpretation. Code is MIT licensed.
Metadata
Release files for fitro-mcp 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fitro_mcp-1.0.0.tar.gz | 187.1 kB | Without provenance | Details for fitro_mcp-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fitro_mcp-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for fitro_mcp-1.0.0-py3-none-any.whl |
Total release size: 215.7 kB
Release files / fitro_mcp-1.0.0.tar.gz
| Download URL | fitro_mcp-1.0.0.tar.gz |
|---|---|
| Size | 187.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4178a420afab6aed12d7fdb32669c66a88e126d20d95099c69e64119218decc0
|
|
BLAKE2b-256 checksum How to use checksums |
1d6d69573c1e5c7486a9737859e0048b8d456eeec8fbafeed4f898ae47a2646f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.13
|
Release files / fitro_mcp-1.0.0-py3-none-any.whl
| Download URL | fitro_mcp-1.0.0-py3-none-any.whl |
|---|---|
| Size | 28.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7473348a2c3f407db6bd3e5b1a86a1ee78b54421668e61da279d3f52e6b8f536
|
|
BLAKE2b-256 checksum How to use checksums |
9ce96c25f8dec44563811596ca1e3427b8f8164c3151f8b0a0f7c82ed491f67c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.13
|
Security for fitro-mcp 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.