intervals-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@intervals-mcp Create a draft plan for next week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Intervals MCP
Local Python client and MCP server for analyzing an Intervals.icu account, building AI-assisted training plans, and applying only managed drafts to the calendar after explicit confirmation.
Intervals.icu is the operational source of truth. When an account is connected to Garmin Connect, this MCP can also read the Garmin-derived activities and wellness data exposed by Intervals.icu. It does not call the Garmin API directly.
Quick start
Install the project and create your local configuration:
uv sync --dev
cp .env.example .env
cp PERSONAL.example.md PERSONAL.mdSet INTERVALS_API_KEY in .env, then register the local MCP server with Codex:
codex mcp add intervals_icu -- \
uv run --directory /absolute/path/to/intervals-mcp intervals-mcpRestart Codex if it was already open, then use /mcp to confirm that intervals_icu is connected. You can now ask Codex things such as:
Read my private training context and list my managed Intervals.icu draft plans.
Read my recent training context and summarize the last two weeks.
Create a draft plan for next week, but show me the preview before writing anything.The server is local and communicates over stdio. It does not send data to a separate service. Read operations can run immediately; every mutation first returns a preview and requires a second call with confirmed=true after explicit approval. Scheduling can make workouts available for Garmin synchronization, but Garmin delivery must still be verified separately.
For Claude Code, use the equivalent command in Connect to Claude Code. For detailed setup, safety rules, and development commands, continue below.
Codex or Claude Code
│
▼ MCP (stdio)
intervals-mcp ──────── Intervals.icu API
│
▼
Library: [IA] ...
│
athlete review
│
apply plan in Intervals
│
▼
Calendar → GarminRelated MCP server: intervals.icu-mcp
Why a skill plus MCP
The skill teaches the LLM the training workflow, workout syntax, and safety guardrails.
The MCP keeps API access outside the conversation context and exposes typed operations.
PERSONAL.example.mdis the tracked template;PERSONAL.mdstores the active athlete's private context and is ignored by Git.The Python client verifies that writes belong to the managed namespace.
Intervals.icu remains the dashboard, calendar, and analysis system.
The MCP provides a deterministic safety boundary around the API: it avoids exposing credentials in prompts and does not provide unrestricted calendar CRUD.
Current capabilities
The server exposes tools for:
Reading private athlete context with
get_personal_contextandset_personal_fact.Reading filtered body and health profile metrics with
get_athlete_profile.Reading activities, wellness, and calendar data with
get_training_contextfor ranges up to 180 days.Reading power, pace, and heart-rate curves with
get_performance_curves.Listing and reading managed plans with
list_draft_plansandget_draft_plan.Creating, cloning, renaming, and editing private managed library plans.
Adding and updating structured workouts inside managed plans.
Applying a managed plan to the calendar from an exact future date with
schedule_draft_plan.Removing only calendar copies from a managed application with
unschedule_draft_plan.Serving
intervals://safety-policy,intervals://personal-context, andintervals://draft-plansresources.Serving the
draft_training_weekMCP prompt.
Generic event create, edit, and delete operations are not exposed. Every mutation first returns a preview with confirmed=false; it can only proceed with confirmed=true after explicit approval.
Local personal memory
Copy PERSONAL.example.md to PERSONAL.md and fill it with the active athlete's private memory. The local file is ignored by Git, and the skill requires reading it before analyzing or changing a plan. Durable information can be stored through set_personal_fact; reusing the same key replaces the previous value.
Store only goals, events, recurring availability, preferences, performance markers, equipment, integrations, and training constraints. Never store examples, guesses, API keys, passwords, tokens, payment data, or sensitive health information unless explicitly requested.
Requirements
Python 3.13 or newer.
uv.An Intervals.icu account and personal API key.
Codex or Claude Code to consume the MCP.
Setup
uv sync --dev
cp .env.example .envThen set INTERVALS_API_KEY in the local .env file. Never commit .env or paste the key into a conversation. Personal Intervals.icu authentication uses HTTP Basic with the literal username API_KEY; the client configures this automatically.
To check read access:
uv run intervals-mcp-cli doctorThe command only lists library containers and does not write anything.
Run and inspect the MCP
uv run intervals-mcpThe process waits for JSON-RPC messages on stdin; this is expected. For visual inspection, use:
uv run mcp dev src/intervals_mcp/mcp_server.py
npx -y @modelcontextprotocol/inspector uv run intervals-mcpConnect to Codex
codex mcp add intervals_icu -- \
uv run --directory /absolute/path/to/intervals-mcp intervals-mcp
codex mcp listUse /mcp inside Codex to inspect the server and its tools. The equivalent configuration is:
[mcp_servers.intervals_icu]
command = "uv"
args = ["run", "intervals-mcp"]
cwd = "/absolute/path/to/intervals-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 90
default_tools_approval_mode = "writes"The writes setting makes Codex request approval for mutating tools. The server also requires its own confirmed=true.
Enable the skill in Codex
mkdir -p .agents/skills
ln -s ../../skills/manage-intervals-icu .agents/skills/manage-intervals-icuConnect to Claude Code
claude mcp add --transport stdio --scope local intervals_icu -- \
uv run --directory /absolute/path/to/intervals-mcp intervals-mcp
claude mcp listFor a project-shared command, use --scope project, which creates .mcp.json. Do not put the API key in that file; every user must keep a local .env.
Claude Code discovers project skills under .claude/skills:
mkdir -p .claude/skills
ln -s ../../skills/manage-intervals-icu .claude/skills/manage-intervals-icuRecommended first run
Run
doctor.Connect the MCP to Codex or Claude Code.
Ask it to use the Intervals.icu skill and list managed drafts.
Request recent training context and verify that no secrets are returned.
Create an empty plan with
confirmed=falseand inspect the preview.Approve the second call with
confirmed=true.Open Intervals.icu and confirm that a private
[IA] ...plan appears.Add one easy session and verify that Intervals.icu interprets its steps correctly.
Preview
schedule_draft_plan, review dates and conflicts, and approve only when ready.
Safety model
A managed plan must have
type == PLANand a description containing[intervals-mcp:managed].[IA]is only a display prefix; security does not depend on the human-facing name.Every edit requires the latest remote content hash.
Only complete managed-plan applications can be scheduled or removed; generic event CRUD is unavailable.
Scheduling rejects past dates, empty plans, stale hashes, and duplicate applications.
Existing events in the target dates require additional approval through
allow_calendar_conflicts=true.Unscheduling resolves IDs by
plan_folder_idand application range, then deletes only those exact events after confirmation.The server never prints the API key or authentication responses.
Scheduling may make eligible workouts available for Garmin synchronization; Garmin delivery must be reported as pending until verified.
Development
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest -q
uv run python scripts/smoke_mcp.pyHTTP tests use a mocked Intervals.icu service. They do not need credentials or modify a real account.
Project status
The client and MCP are implemented and tested against the current public Intervals.icu contract. A manual test with a real API key is still needed to verify exactly how the library displays plans and processes workouts in a specific account.
Available Tools
14 toolsadd_workout_to_draftC
Add one structured workout to a managed library plan.
Inputs: day (required), name (required), plan_id (required), description (required), +7 more. Returns: object
clone_draft_planC
Clone a managed draft plan to preserve a version before editing.
Inputs: plan_id (required), expected_hash (required), version_label (required), confirmed. Returns: object
create_draft_planC
Create a private managed library PLAN; never apply it to the calendar.
Inputs: name (required), description (required), confirmed, activity_types. Returns: object
get_athlete_profileARead-only
Read health and body-composition fields from the athlete profile only.
Inputs: no named parameters. Returns: object
get_draft_planARead-only
Read a managed plan and its workouts; reject plans outside the draft namespace.
Inputs: plan_id (required). Returns: object
get_performance_curvesBRead-only
Read power, pace, and heart-rate duration curves without modifying data.
Inputs: sport (required), curves. Returns: object
get_personal_contextARead-only
Read durable athlete preferences and constraints before planning or editing.
Inputs: no named parameters. Returns: object
get_training_contextARead-only
Read activities, wellness and calendar events for an inclusive ISO date range.
Inputs: newest (required), oldest (required). Returns: object
list_draft_plansARead-only
List only plans managed by this server, including their current content hashes.
Inputs: no named parameters. Returns: object
rename_draft_planC
Rename one managed library plan using the configured short display prefix.
Inputs: name (required), plan_id (required), expected_hash (required), confirmed. Returns: object
schedule_draft_planC
Apply one managed draft plan to the calendar on an exact future ISO date.
Inputs: plan_id (required), start_date (required), expected_hash (required), confirmed, +1 more. Returns: object
set_personal_factBIdempotent
Remember one durable, non-secret athlete fact; the same section/key is replaced safely.
Inputs: key (required), value (required), section (required). Returns: object
unschedule_draft_planBDestructive
Delete only calendar copies from one managed plan application; keep the library plan.
Inputs: plan_id (required), start_date (required), expected_hash (required), confirmed. Returns: object
update_draft_workoutB
Replace one workout on a managed plan after checking the plan hash.
Inputs: day (required), name (required), plan_id (required), workout_id (required), +8 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool addresses a distinct operation: draft plan lifecycle (create, clone, rename, get, list, schedule, unschedule), workout management (add, update), athlete context (profile, personal context, fact), and performance data. No two tools have overlapping purposes.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., rename_draft_plan, get_training_context, set_personal_fact). The convention is uniform across all 14 tools.
14 tools cover the domain of training plan management (library plans, workouts, scheduling, athlete data, performance curves) without being excessive or too sparse. Each tool has a clear role.
Core workflows for draft plans are present (create, read, update via rename/add_workout/update_workout, schedule/unschedule), but missing delete operations (no delete_draft_plan or remove_workout_from_draft). This gap could cause issues if agents need to remove plans or workouts.
Maintenance
Related MCP Connectors
Adaptive running coach MCP server — training data, plans, and recovery for AI assistants.
Remote MCP server for training, nutrition, wellness, and performance data with OAuth 2.0.
MCP server for generating rough-draft project plans from natural-language prompts.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server for Intervals.icu integration. Access your training data, wellness metrics, and performance analysis through Claude and other LLMs.4839MIT
- AlicenseAqualityCmaintenanceMCP server for Intervals.icu that enables AI assistants to manage athletic training data, including activities, calendar events, wellness metrics, and workout libraries.19Apache 2.0
- AlicenseBqualityBmaintenanceMCP server for local fitness-data extraction and analysis from Garmin Connect, Intervals.icu, and Strava. Provides read-only analytical tools over DuckDB and targeted Strava enrichment.35469 npm1AGPL 3.0
- AlicenseAqualityBmaintenanceMCP server that connects AI agents to Intervals.icu, enabling access to training data such as activities, wellness metrics, calendar events, gear, power curves, and custom items. Includes a running coach AI template for automated post-session analysis.1929 npm1MIT