XERT MCP Server

1# XERT MCP Server
2 
3A Model Context Protocol (MCP) server that connects Claude to the XERT API, providing access to your fitness signature, training load, workouts, and activities.
4 
5## Features
6 
7- 📊 **Fitness Signature** - Get your current FTP, LTP, HIE, and Peak Power
8- 🎯 **Training Status** - Check freshness, training load, and recommended XSS
9- 🏋️ **Workout of the Day** - AI-powered workout recommendations
10- 📋 **Workouts** - List, view details, and export (ZWO/ERG)
11- 🚴 **Activities** - Browse activities with full XSS metrics and MPA data
12- ⬆️ **Upload** - Upload FIT files for analysis
13 
14## Installation
15 
16### Prerequisites
17 
18- Node.js 18 or later
19- A XERT account (free or premium)
20 
21### Setup
22 
231. **Clone the repository:**
24   ```bash
25   git clone https://github.com/Milofax/xert-mcp.git
26   cd xert-mcp
27   ```
28 
292. **Install dependencies:**
30   ```bash
31   npm install
32   ```
33 
343. **Authenticate with XERT:**
35   ```bash
36   npm run setup-auth
37   ```
38   Enter your XERT email and password when prompted. Tokens will be saved to `.env`.
39 
404. **Build the project:**
41   ```bash
42   npm run build
43   ```
44 
45## Configuration
46 
47Add to your Claude Desktop config:
48 
49**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
50**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
51 
52```json
53{
54  "mcpServers": {
55    "xert": {
56      "command": "node",
57      "args": ["/path/to/xert-mcp/dist/server.js"]
58    }
59  }
60}
61```
62 
63Replace `/path/to/xert-mcp` with the actual path to your installation.
64 
65Restart Claude Desktop to load the server.
66 
67### Docker
68 
69You can also run the server via Docker:
70 
71#### 1. Build the image
72 
73```bash
74docker build -t xert-mcp .
75```
76 
77#### 2. Get your XERT tokens
78 
79Run the setup script locally first to authenticate:
80 
81```bash
82npm install
83npm run setup-auth
84```
85 
86This creates `xert-tokens.json` with your access and refresh tokens.
87 
88#### 3. Configure Claude Desktop
89 
90```json
91{
92  "mcpServers": {
93    "xert": {
94      "command": "docker",
95      "args": [
96        "run", "-i", "--rm",
97        "-e", "XERT_ACCESS_TOKEN",
98        "-e", "XERT_REFRESH_TOKEN",
99        "xert-mcp"
100      ],
101      "env": {
102        "XERT_ACCESS_TOKEN": "your-access-token-from-xert-tokens.json",
103        "XERT_REFRESH_TOKEN": "your-refresh-token-from-xert-tokens.json"
104      }
105    }
106  }
107}
108```
109 
110**Note:** Access tokens expire after 7 days. When they expire, run `npm run setup-auth` again and update the tokens in your config.
111 
112## Available Tools
113 
114| Tool | Description |
115|------|-------------|
116| `xert-get-training-info` | Get fitness signature, training status, load, and WOTD |
117| `xert-list-workouts` | List all your saved workouts |
118| `xert-get-workout` | Get detailed workout intervals |
119| `xert-download-workout` | Export workout as ZWO or ERG file |
120| `xert-list-activities` | List activities in a time range |
121| `xert-get-activity` | Get activity details with XSS metrics |
122| `xert-upload-fit` | Upload a FIT file for analysis |
123 
124## Usage Examples
125 
126Ask Claude questions like:
127 
128- "What's my current FTP and training status?"
129- "Show me my workout of the day"
130- "List my activities from the last 7 days"
131- "What was my XSS breakdown for yesterday's ride?"
132- "Did I have any breakthroughs this week?"
133- "Show me my saved workouts"
134- "Export my 'Sunday Endurance' workout as a ZWO file"
135 
136## XERT Concepts
137 
138- **FTP** - Functional Threshold Power (1-hour sustainable power)
139- **LTP** - Lower Threshold Power (fat-burning threshold)
140- **HIE** - High Intensity Energy (anaerobic work capacity)
141- **PP** - Peak Power (maximum instantaneous power)
142- **XSS** - Xert Strain Score (training load metric)
143- **MPA** - Maximum Power Available (real-time power limit)
144 
145## Development
146 
147```bash
148# Run in development mode
149npm run dev
150 
151# Build for production
152npm run build
153 
154# Start production server
155npm start
156```
157 
158## Token Management
159 
160The server handles tokens automatically:
161 
162- **Access tokens** expire after 7 days
163- **Refresh tokens** expire after 6 months
164- Tokens are stored in `xert-tokens.json` (created automatically)
165- On 401 errors, tokens are refreshed automatically
166- New tokens are persisted to survive server restarts
167 
168If authentication fails completely, run `npm run setup-auth` again.
169 
170### MCP Funnel / Environment Variables
171 
172When using mcp-funnel or similar tools, tokens from `xert-tokens.json` take priority over environment variables. This ensures refreshed tokens are used even when env vars contain outdated values.
173 
174## License
175 
176MIT
177 
178## Credits
179 
180- [XERT](https://www.xertonline.com/) - Advanced cycling analytics
181- [Model Context Protocol](https://modelcontextprotocol.io/) - AI integration standard
182