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