igpsport-mcp

English | 简体中文

A local MCP server that connects your iGPSport cycling data to LLM clients like Claude. Analyze your training in natural language: "How's my training load this week?" "Compare my two long rides from last week and this week." "What's my ranking on that climb I starred?" "How many kilometers did I ride this year, and what are my personal bests?" — and even have Claude prescribe workouts for you: "Build me a 2×20 SST session based on my FTP and push it to my head unit."

Key differentiator: Derived training metrics — NP / IF / TSS / CTL / ATL / TSB — are computed server-side in the MCP layer before being returned. The LLM receives story-ready numbers, not raw stream data.

You:   What's my training load trend over the last 90 days? Should I back off?
Claude (via analyze_training_load):
       Current CTL (Fitness) 72, ATL (Fatigue) 91, TSB (Form) -19 — you're in a significant fatigue hole.
       TSS has been above CTL for the past two weeks. Consider a 3–5 day recovery block to get TSB back above -5…

Demo

⚠️ Unofficial project. This tool works by simulating iGPSport web client requests. iGPSport may change their API at any time, which could break functionality. Please evaluate account risk yourself — use at your own risk. Runs entirely locally over stdio — your data never touches any third-party server.

Quick Start (Recommended)

This tool is an MCP server and requires an MCP-capable client (e.g. Claude Desktop / Claude Code / Cursor). Once you have a client ready, three steps:

1. Install uv (a standalone tool — you do not need Python pre-installed, uv handles the runtime automatically):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Install globally and run the setup wizard (interactively enter your phone/email and password — credentials stay local). The commands are the same on both systems; run them in Terminal on macOS or PowerShell on Windows:

uv tool install igpsport-mcp
igpsport-mcp --setup

If igpsport-mcp is not found after installation, open a new terminal/PowerShell window so PATH updates take effect (uv places executables in ~/.local/bin on macOS, %USERPROFILE%\.local\bin on Windows).

The wizard saves credentials to a config file (owner-readable only) and prints a copy-paste ready MCP configuration block. Config file locations:

• macOS: ~/.igpsport-mcp/config.json
• Windows: C:\Users\YourName\.igpsport-mcp\config.json

3. Paste the printed config into your client, then restart the client (see "Connect to Claude" below).

Want to verify your credentials before pasting? Run igpsport-mcp --check — it performs a real login and prints ✅ success or ❌ the reason for failure, so you don't add it to your client only to find it broken.

Need to print the config snippet again later? igpsport-mcp --mcp-config anytime.

Developers / users with an existing Python environment: use uvx igpsport-mcp for one-shot runs, or configure via environment variables below instead of the wizard.

CLI Usage

Running with no arguments starts the MCP server in stdio mode (this is what your MCP client invokes — you normally don't run it manually). Other subcommands:

Configuration (Environment Variables)

Users who ran the --setup wizard can skip this section — credentials are already stored. The section below is for users who prefer environment variables, or need to manage credentials across CI / multiple environments. Env vars take priority over config.json.

FTP / LTHR are now auto-read from your iGPSport athlete profile by default (along with body weight and max HR), so you normally don't need to set them manually. Only set the env vars when you want to use thresholds different from what's in the app. If your iGPSport profile also has no FTP set, IF / TSS / CTL / ATL / TSB cannot be computed — either add FTP in iGPSport or set IGPSPORT_FTP.

International Edition Support

Switch to the international edition (app.igpsport.com) by setting IGPSPORT_REGION=intl. The international and China servers use separate accounts — you must register separately at app.igpsport.com.

Differences from the China server:

• No WASM signing — authentication uses pure JWT, a simpler design
• Segment features are unavailable (international segments are in beta, listing is empty)
• Training parameter endpoint uses v2 path; yearly statistics path differs (auto-adapted internally)
• Workout course format is cross-region compatible — zero changes in the IR compilation layer

Example configuration:

# via env vars
export IGPSPORT_REGION=intl
export IGPSPORT_USERNAME=your_email@example.com
export IGPSPORT_PASSWORD=your_password

Or select "2. International" in the first step of the --setup wizard.

International edition FIT files are stored on OSS in the US (oss-us-west-1). Downloads may be slightly slower for users in China.

Connect to Claude

Claude Desktop

Open the config file claude_desktop_config.json (create it if it doesn't exist), paste the content below, then fully quit and reopen Claude Desktop. File locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json (i.e. C:\Users\You\AppData\Roaming\Claude\claude_desktop_config.json)

You can also open this file directly from Claude Desktop via Settings → Developer → Edit Config.

After running --setup (credentials in config.json, leave env empty — this is what --mcp-config prints):

{
  "mcpServers": {
    "igpsport": {
      "command": "igpsport-mcp",
      "args": [],
      "env": {}
    }
  }
}

Or skip the wizard and use uvx with environment variables:

{
  "mcpServers": {
    "igpsport": {
      "command": "uvx",
      "args": ["igpsport-mcp"],
      "env": {
        "IGPSPORT_USERNAME": "your_phone_or_email",
        "IGPSPORT_PASSWORD": "your_password"
      }
    }
  }
}

FTP / LTHR are auto-read from your iGPSport profile by default — no need to set them. Only add "IGPSPORT_FTP": "250" or "IGPSPORT_LTHR": "160" in env if you want to override what's in the app.

Claude Code

After the wizard (credentials stored):

claude mcp add igpsport --scope user -- igpsport-mcp

Or with uvx + env vars:

claude mcp add igpsport --scope user \
  --env IGPSPORT_USERNAME=your_phone_or_email \
  --env IGPSPORT_PASSWORD=your_password \
  -- uvx igpsport-mcp

Verify with /mcp or claude mcp list — status should be connected.

OpenClaw

OpenClaw uses stdio for MCP, the same protocol as Claude Desktop / Claude Code, so the configuration above works directly.

Method 1: Ask OpenClaw in natural language (recommended)

First install with uv tool install igpsport-mcp and run igpsport-mcp --setup. Then, in your connected chat channel, simply tell OpenClaw:

I installed igpsport-mcp. Help me configure it in OpenClaw.

It will locate the binary path, verify credentials with igpsport-mcp --check, write the config via openclaw mcp add, and probe it — all without you touching a command line or JSON.

Method 2: One-liner

# After the wizard (credentials stored)
openclaw mcp add igpsport --command igpsport-mcp

# Or with uvx + env vars
openclaw mcp add igpsport --command uvx --args igpsport-mcp \
  --env IGPSPORT_USERNAME=your_phone_or_email \
  --env IGPSPORT_PASSWORD=your_password

This writes to ~/.openclaw/openclaw.json under mcp.servers.igpsport. You can also edit the file manually:

{
  mcp: {
    servers: {
      igpsport: {
        command: "igpsport-mcp",
        args: [],
        env: {}
      }
    }
  }
}

Verification:

openclaw mcp list      # should show igpsport
openclaw mcp status    # igpsport: stdio
openclaw mcp probe     # igpsport: 17 tools, resources, prompts

The mcp field is hot-reloaded — no gateway restart needed; it takes effect in the next conversation turn. Use openclaw mcp reload to force-refresh the runtime cache if needed. Then ask questions in natural language from any connected channel (Discord, Telegram, Slack, etc.).

Not connecting? Run igpsport-mcp --check in a terminal first to isolate the problem:

• ❌ Login failed → credential issue; re-run igpsport-mcp --setup.

• ✅ Success but the client still can't connect → likely igpsport-mcp / uvx isn't in the client's PATH (Claude Desktop in particular often can't see the login shell's PATH). Replace command in the config with the absolute path:

• macOS: run which igpsport-mcp (or which uvx) in Terminal, e.g. /Users/You/.local/bin/igpsport-mcp.

• Windows: run where.exe igpsport-mcp (or where.exe uvx) in PowerShell, e.g. C:\Users\You\.local\bin\igpsport-mcp.exe. In JSON, backslashes must be doubled, e.g. "command": "C:\\Users\\You\\.local\\bin\\igpsport-mcp.exe".

Updates

For uv tool install installations (both systems), upgrade to the latest:

uv tool upgrade igpsport-mcp

Restart your client after upgrading (fully quit and reopen Claude Desktop; reconnect for Claude Code). Check current version: igpsport-mcp --version.

For uvx igpsport-mcp one-shot users, no manual upgrade is needed — uvx uses the latest version by default. If a stale version is cached locally, use uvx igpsport-mcp@latest or clear the cache with uv cache clean first.

Uninstall

1. Remove the program (same for both systems):

uv tool uninstall igpsport-mcp

2. Remove local credentials and cache (optional, for a complete cleanup):

# macOS / Linux (Terminal)
rm -rf ~/.igpsport-mcp        # credentials (config.json)
rm -rf ~/.cache/igpsport-mcp  # tokens, SQLite, FIT file cache

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.igpsport-mcp"
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\igpsport-mcp"

3. Remove igpsport from your client config: Claude Desktop — delete the igpsport block under mcpServers in claude_desktop_config.json; Claude Code — claude mcp remove igpsport; OpenClaw — openclaw mcp unset igpsport (or delete the igpsport block under mcp.servers in ~/.openclaw/openclaw.json).

For uvx igpsport-mcp one-shot users, there is no "program" to uninstall — just do steps 2 and 3.

17 Tools Provided

Activities & Training (9)

Segments (3)

Statistics & Achievements (1)

Training Courses (4) — the only "write" capability

Power targets support absolute watts, %FTP (auto-converted using your FTP), and power zones; heart rate, cadence, and speed targets are also supported. Duration can be set by time / distance / calories / manual lap button. Created workouts appear in the iGPSport app under "Training Courses" and can be synced to your head unit for execution.

Derived Metrics Reference

• NP (Normalized Power): ((30 s rolling average power)^4 mean)^0.25; stream is resampled to 1 Hz before computation.
• IF = NP / FTP; TSS = duration_s × NP × IF / (FTP × 3600) × 100.
• CTL / ATL / TSB: exponential weighted moving averages of daily TSS (α = 1/42, 1/7); TSB = CTL − ATL.
• No-power-meter fallback: hrTSS = (duration_s / 3600) × (avg HR / LTHR)² × 100, annotated estimated from HR.
• Zone models: HR uses Friel (LTHR-based); Power uses Coggan 7-zone (FTP-based).

FAQ

Q: Do I need a power meter? A: No. Without a power meter, heart-rate-based metrics work normally and TSS falls back to hrTSS (lower accuracy, annotated as such). However, setting FTP is recommended to unlock power-based metrics.

Q: Is my data uploaded anywhere? A: Not to any third party. Other than reading/writing your own iGPSport account data (reading activities/stats, and create_workout/delete_workout for your own training courses), everything happens locally. FIT files and derived metrics are cached locally.

Q: Can create_workout / delete_workout mess up my data? A: create_workout only adds new training courses — you can use dry_run=true to preview the compiled result before deciding to send. delete_workout is irreversible and defaults to a confirmation preview; it requires explicit confirm=true to actually delete — so an LLM cannot delete a course without your confirmation.

Q: Does with_calendar automatically write to my calendar? A: No. This server only produces a standard iCalendar (VEVENT) text artifact — it never touches any calendar API or sends data externally. Whether the event is actually written to a calendar is up to your LLM client to hand off to another calendar/reminder tool (e.g. Apple Calendar, Reminders, or a Notion MCP). Since a workout is a template with no execution date, the DTSTART is the placeholder {{SCHEDULED_DATE}} — the downstream consumer fills in the actual date.

Q: What if the API breaks? A: iGPSport may change their API, which could cause breakage — the tool will throw a clear error. Please report issues at Issues.

Q: Does it support running / other head units? A: No. This project focuses exclusively on iGPSport cycling data.

Q: What's different about the international edition? A: International and China server accounts are separate. The international edition lacks segment features (beta, listing is empty) and uses a simpler authentication mechanism (no WASM signing). Activities, training courses, and statistics work the same. See the "International Edition Support" section for details.

Development

uv sync --extra dev
uv run pytest            # tests
uv run pytest -m integration   # online integration tests
ruff check . && ruff format .  # lint / format

License

MIT. This project is not affiliated with iGPSport in any way.