Skip to content
Back to search

intervals-mcp-server

Model Context Protocol (MCP) server for connecting Claude and ChatGPT with the Intervals.icu API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mvilanova--intervals-mcp-server/badge.svg)](/listings/mvilanova--intervals-mcp-server)

HTML

<a href="/listings/mvilanova--intervals-mcp-server"><img src="/api/listings/mvilanova--intervals-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

1. Install uv (recommended)

**macOS/Linux:**

curl -LsSf https://astral.sh/uv/install.sh | sh

**Windows (PowerShell):**

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, find the full path to `uv` — you'll need it later when configuring Claude Desktop:

where.exe uv
# Example output: C:\Users\<USERNAME>\.local\bin\uv.exe

2. Clone this repository

git clone https://github.com/mvilanova/intervals-mcp-server.git
cd intervals-mcp-server

3. Create and activate a virtual environment

# Create virtual environment with Python 3.12
uv venv --python 3.12

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

4. Sync project dependencies

uv sync

5. Set up environment variables

Make a copy of `.env.example` and name it `.env` by running the following command:

**macOS/Linux:**

cp .env.example .env

**Windows (PowerShell):**

Copy-Item .env.example .env

Then edit the `.env` file and set your Intervals.icu athlete id and API key:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

Getting your Intervals.icu API Key

1. Log in to your Intervals.icu account 2. Go to Settings > API 3. Generate a new API key

Finding your Athlete ID

Your athlete ID is typically visible in the URL when you're logged into Intervals.icu. It looks like:

- `https://intervals.icu/athlete/i12345/...` where `i12345` is your athlete ID

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 379 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Intervals.icu MCP Server
  2. Model Context Protocol (MCP) server for connecting Claude and ChatGPT with the Intervals.icu API. It provides tools for authentication and data retrieval for activities, events, wellness data, power curves, and custom items.
  3. If you find the Model Context Protocol (MCP) server useful, please consider supporting its continued development with a donation.
  4. ## Requirements
  5. - Python 3.12 or higher
  6. - [Model Context Protocol (MCP) Python SDK](https://github.com/modelcontextprotocol/python-sdk)
  7. - httpx
  8. - python-dotenv
  9. ## Setup
  10. ### 1. Install uv (recommended)
  11. **macOS/Linux:**
  12. ```bash
  13. curl -LsSf https://astral.sh/uv/install.sh | sh
  14. ```
  15. **Windows (PowerShell):**
  16. ```powershell
  17. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  18. ```
  19. After installation, find the full path to `uv` — you'll need it later when configuring Claude Desktop:
  20. ```powershell
  21. where.exe uv
  22. # Example output: C:\Users\<USERNAME>\.local\bin\uv.exe
  23. ```
  24. ### 2. Clone this repository
  25. ```bash
  26. git clone https://github.com/mvilanova/intervals-mcp-server.git
  27. cd intervals-mcp-server
  28. ```
  29. ### 3. Create and activate a virtual environment
  30. ```bash
  31. # Create virtual environment with Python 3.12
  32. uv venv --python 3.12
  33. # Activate virtual environment
  34. # On macOS/Linux:
  35. source .venv/bin/activate
  36. # On Windows:
  37. .venv\Scripts\activate
  38. ```
  39. ### 4. Sync project dependencies
  40. ```bash
  41. uv sync
  42. ```
  43. ### 5. Set up environment variables
  44. Make a copy of `.env.example` and name it `.env` by running the following command:
  45. **macOS/Linux:**
  46. ```bash
  47. cp .env.example .env
  48. ```
  49. **Windows (PowerShell):**
  50. ```powershell
  51. Copy-Item .env.example .env
  52. ```
  53. Then edit the `.env` file and set your Intervals.icu athlete id and API key:
  54. ```
  55. API_KEY=your_intervals_api_key_here
  56. ATHLETE_ID=your_athlete_id_here
  57. ```
  58. #### Getting your Intervals.icu API Key
  59. 1. Log in to your Intervals.icu account
  60. 2. Go to Settings > API
  61. 3. Generate a new API key
  62. #### Finding your Athlete ID
  63. Your athlete ID is typically visible in the URL when you're logged into Intervals.icu. It looks like:
  64. - `https://intervals.icu/athlete/i12345/...` where `i12345` is your athlete ID
  65. ## Updating
  66. This project is actively developed, with new features and fixes added regularly. To stay up to date, follow these steps:
  67. ### 1. Pull the latest changes from `main`
  68. > ⚠️ Make sure you don't have uncommitted changes before running this command.
  69. **macOS/Linux:**
  70. ```bash
  71. git checkout main && git pull
  72. ```
  73. **Windows (PowerShell):**
  74. ```powershell
  75. git checkout main; git pull
  76. ```
  77. ### 2. Update Python dependencies
  78. Activate your virtual environment and sync dependencies:
  79. **macOS/Linux:**
  80. ```bash
  81. source .venv/bin/activate
  82. uv sync
  83. ```
  84. **Windows (PowerShell):**
  85. ```powershell
  86. .venv\Scripts\activate
  87. uv sync
  88. ```
  89. ### Troubleshooting
  90. If Claude Desktop fails due to configuration changes, follow these steps:
  91. 1. Delete the existing `Intervals.icu` entry in `claude_desktop_config.json`.
  92. 2. Reconfigure Claude Desktop from the `intervals-mcp-server` directory.
  93. **macOS/Linux:**
  94. ```bash
  95. mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env
  96. ```
  97. **Windows:** Re-add the entry manually as described in the [Windows configuration section](#windows).
  98. #### Common errors
  99. **`spawn uv ENOENT`** — Claude Desktop cannot find the `uv` executable. Use the full path to `uv` in the `command` field. Run `which uv` (macOS/Linux) or `where.exe uv` (Windows) to get it.
  100. **`spawn /Users/... ENOENT` on Windows** — The config file contains a macOS/Linux-style path. Replace it with the correct Windows path using backslashes as described in the [Windows configuration section](#windows) below.
  101. **Windows Store install: config changes not taking effect** — You may be editing the wrong config file. Claude Desktop installed from the Microsoft Store reads from `AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`, not `AppData\Roaming\Claude\`.
  102. ## Usage with Claude
  103. ### 1. Configure Claude Desktop
  104. To use this server with Claude Desktop, you need to add it to your Claude Desktop configuration.
  105. #### macOS/Linux
  106. 1. Run the following from the `intervals-mcp-server` directory to configure Claude Desktop:
  107. ```bash
  108. mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env
  109. ```
  110. 2. If you open your Claude Desktop App configuration file `claude_desktop_config.json`, it should look like this:
  111. ```json
  112. {
  113. "mcpServers": {
  114. "Intervals.icu": {
  115. "command": "/Users/<USERNAME>/.local/bin/uv",
  116. "args": [
  117. "run",
  118. "--with",
  119. "mcp[cli]",
  120. "--with-editable",
  121. "/path/to/intervals-mcp-server",
  122. "mcp",
  123. "run",
  124. "/path/to/intervals-mcp-server/src/intervals_mcp_server/server.py"
  125. ],
  126. "env": {
  127. "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
  128. "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
  129. "API_KEY": "<YOUR_API_KEY>",
  130. "LOG_LEVEL": "INFO"
  131. }
  132. }
  133. }
  134. }
  135. ```
  136. Where `/path/to/` is the path to the `intervals-mcp-server` code folder in your system.
  137. #### Windows
  138. The `mcp install` command may fail on Windows due to environment or permission issues. Instead, configure Claude Desktop manually:
  139. 1. Find the Claude Desktop config file. If Claude Desktop was installed from the **Microsoft Store**, the config is located at:
  140. ```
  141. C:\Users\<USERNAME>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
  142. ```
  143. If installed via the standard installer, it may be at:
  144. ```
  145. C:\Users\<USERNAME>\AppData\Roaming\Claude\claude_desktop_config.json
  146. ```
  147. If the file or folder does not exist, create it.
  148. 2. Add the following entry to `claude_desktop_config.json`, replacing the placeholders with your actual values:
  149. ```json
  150. {
  151. "mcpServers": {
  152. "Intervals.icu": {
  153. "command": "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe",
  154. "args": [
  155. "run",
  156. "--with",
  157. "mcp[cli]",
  158. "--with-editable",
  159. "C:\\path\\to\\intervals-mcp-server",
  160. "mcp",
  161. "run",
  162. "C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py"
  163. ],
  164. "env": {
  165. "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
  166. "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
  167. "API_KEY": "<YOUR_API_KEY>",
  168. "LOG_LEVEL": "INFO"
  169. }
  170. }
  171. }
  172. }
  173. ```
  174. - Use double backslashes (`\\`) for all Windows paths in JSON.
  175. - To find the full path to `uv.exe`, run `where.exe uv` in PowerShell.
  176. - To find the full path to the cloned repository, run `pwd` from inside the `intervals-mcp-server` folder.
  177. > **Note for Windows Store installs:** Claude Desktop installed from the Microsoft Store sandboxes its config under `AppData\Local\Packages\...`. Editing `AppData\Roaming\Claude\claude_desktop_config.json` will have no effect — make sure you edit the correct file.
  178. 3. Restart Claude Desktop.
  179. ### 2. Use the MCP server with Claude
  180. Once the server is running and Claude Desktop is configured, you can use the following tools to ask questions about your past and future activities, events, and wellness data.
  181. - `get_activities`: Retrieve a list of activities
  182. - `get_activity_details`: Get detailed information for a specific activity
  183. - `get_activity_intervals`: Get detailed interval data for a specific activity
  184. - `get_activity_streams`: Get raw data streams (power, heart rate, etc.) for a specific activity
  185. - `get_athlete_power_curves`: Get best power output curves for selected durations and time periods
  186. - `get_wellness_data`: Fetch wellness data
  187. - `get_events`: Retrieve upcoming events (workouts, races, etc.)
  188. - `get_event_by_id`: Get detailed information for a specific event
  189. - `add_or_update_event`: Create or update an event (workout, race, note, etc.)
  190. - `delete_event`: Delete a specific event
  191. - `delete_events_by_date_range`: Delete events within a date range
  192. - `get_custom_items`: Get custom items (charts, custom fields, zones, etc.) for an athlete
  193. - `get_custom_item_by_id`: Get detailed information for a specific custom item
  194. - `create_custom_item`: Create a new custom item for an athlete
  195. - `update_custom_item`: Update an existing custom item
  196. - `delete_custom_item`: Delete a custom item
  197. ## Usage with ChatGPT
  198. ChatGPT’s beta MCP connectors can also talk to this server over the SSE transport.
  199. 1. Start the server in SSE mode so it exposes the `/sse` and `/messages/` endpoints:
  200. ```bash
  201. export FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8765 MCP_TRANSPORT=sse FASTMCP_LOG_LEVEL=INFO
  202. python src/intervals_mcp_server/server.py
  203. ```
  204. The startup log prints the full URLs (for example `http://127.0.0.1:8765/sse`). ChatGPT needs that public URL, so forward the port with a tool such as `ngrok http 8765` if you are not exposing the server directly.
  205. 2. In ChatGPT, open **Settings → Features → Custom MCP Connectors** and click **Add**. Fill in:
  206. - **Name**: `Intervals.icu`
  207. - **MCP Server URL**: `https://<your-public-host>/sse`
  208. - **Authentication**: leave as _No authentication_ unless you have protected your tunnel.
  209. You can reuse the same `ngrok http 8765` tunnel URL here; just ensure it forwards to the host/port you exported above.
  210. 3. Save the connector and open a new chat. ChatGPT will keep the SSE connection open and POST follow-up requests to the `/messages/` endpoint announced by the server. If you restart the MCP server or tunnel, rerun the SSE command and update the connector URL if it changes.
  211. ## Development and testing
  212. Install development dependencies and run the test suite with:
  213. ```bash
  214. uv sync --all-extras
  215. pytest -v tests
  216. ```
  217. ### Running the server locally
  218. To start the server manually (useful when developing or testing), run:
  219. ```bash
  220. mcp run src/intervals_mcp_server/server.py
  221. ```
  222. #### Enabling debug logging
  223. To capture server logs for debugging, wrap the command in a shell and redirect stderr to a file.
  224. **macOS/Linux** — modify your `claude_desktop_config.json` like this:
  225. ```json
  226. {
  227. "mcpServers": {
  228. "Intervals.icu": {
  229. "command": "/bin/bash",
  230. "args": [
  231. "-c",
  232. "/Users/<USERNAME>/.local/bin/uv run --with 'mcp[cli]' --with-editable /path/to/intervals-mcp-server mcp run /path/to/intervals-mcp-server/src/intervals_mcp_server/server.py 2>> /path/to/intervals-mcp-server/mcp-server.log"
  233. ],
  234. "env": {
  235. "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
  236. "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
  237. "API_KEY": "<YOUR_API_KEY>",
  238. "LOG_LEVEL": "INFO"
  239. }
  240. }
  241. }
  242. }
  243. ```
  244. Then tail the log file to see output in real-time:
  245. ```bash
  246. tail -f /path/to/intervals-mcp-server/mcp-server.log
  247. ```
  248. **Windows** — modify your `claude_desktop_config.json` like this:
  249. ```json
  250. {
  251. "mcpServers": {
  252. "Intervals.icu": {
  253. "command": "powershell",
  254. "args": [
  255. "-Command",
  256. "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe run --with 'mcp[cli]' --with-editable C:\\path\\to\\intervals-mcp-server mcp run C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py 2>> C:\\path\\to\\intervals-mcp-server\\mcp-server.log"
  257. ],
  258. "env": {
  259. "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
  260. "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
  261. "API_KEY": "<YOUR_API_KEY>",
  262. "LOG_LEVEL": "INFO"
  263. }
  264. }
  265. }
  266. }
  267. ```
  268. Then monitor the log file in real-time using PowerShell:
  269. ```powershell
  270. Get-Content C:\path\to\intervals-mcp-server\mcp-server.log -Wait
  271. ```
  272. ## License
  273. The GNU General Public License v3.0
  274. ## Featured
  275. ### Glama.ai
  276. <a href="https://glama.ai/mcp/servers/@mvilanova/intervals-mcp-server">
  277. <img width="380" height="200" src="https://glama.ai/mcp/servers/@mvilanova/intervals-mcp-server/badge" alt="Intervals.icu Server MCP server" />
  278. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.