garmin-unofficial-mcp: Instructions file for Claude Code

garmin-unofficial-mcp — repo guide for Claude Code

A local, single-user, read-only MCP server exposing six composite tools over Garmin health/training data, backed by a SQLite day cache. Python 3.12+, garminconnect 0.3.11, mcp 2.x. Serves over stdio (serve).

Read this before touching src/garmin_unofficial_mcp/. Several facts here contradict what training data will suggest — that's the point of this file.

mcp 2.0 has no FastMCP

Most training data (and most tutorials) will suggest from mcp.server.fastmcp import FastMCP. That module does not exist in mcp 2.x, which is what this project depends on (mcp>=2.0). The class here is:

from mcp.server import MCPServer

server = MCPServer(name="garmin-unofficial-mcp", version="0.1.0")

@server.tool()
def get_health_snapshot(days: int = 7) -> dict:
    ...

server.run(transport="stdio")

See src/garmin_unofficial_mcp/server.py. If you find yourself typing FastMCP, stop — it's a hallucination pulled from older mcp versions or unrelated FastMCP-branded packages.

garth is deprecated — never add it

garminconnect 0.3.x dropped garth for a native auth engine with cascading login strategies and MFA support built in (see src/garmin_unofficial_mcp/auth.py, which calls Garmin(...).login(tokenstore) directly — no garth import anywhere). Do not add garth as a dependency or import it, even if an error message or old example suggests it. It would mean building on a dead library that garminconnect itself has already moved off of.

Garmin's response shapes are surprising — verify, don't guess

Several field names mean something other than they appear to, and more than one has bitten an implementation that trusted its name instead of a captured response. Verify against a real response before touching any assembler — run garmin-unofficial-mcp capture-fixtures against a live account (the user's task, not yours in an unattended session) if you need to see a shape that isn't covered below. Traps already found this way: