Intervals MCP server

Intervals Extra (intervals-mcp)

A single-user remote MCP server for intervals.icu run data and analysis, with interactive MCP Apps.

All twenty text tools and every MCP App talk to intervals.icu directly and are verified against a real account; see docs/tools.md for the full catalog. The presence of INTERVALSAPIKEY is checked at startup and reported on /health.

History. This project began as strava-mcp and was migrated to intervals.icu as its data source; nothing in the server talks to Strava today.

Setup

1. Get an intervals.icu API key

1. Log in to intervals.icu
2. Go to Settings, Developer Settings
3. Copy your personal API key

2. Configure environment

cp .env.example .env

Edit .env with your values:

INTERVALS_API_KEY=your_api_key

All variables are listed in docs/operations.md.

3. Run it

Local development (needs Bun):

bun install
bun run dev

Docker:

docker compose up -d

Prefer the prebuilt image? Pull ghcr.io/ljcl/intervals-mcp:latest (also on the MCP registry as io.github.ljcl/intervals-mcp) and point your compose image: at it instead of building; you still supply your own API key. Published images carry SBOM/provenance attestations you can verify; see operations.md.

GET /health reports liveness without spending an intervals.icu API request; with MCPAUTHTOKEN it also reports config and rate-limit state. Response shapes and monitoring guidance: operations.md.

Point any client at http://localhost:3000/mcp. Repo layout, task runner, tests, coverage gates, and Storybook workflow: docs/development.md. Agent conventions live in AGENTS.md.

Connecting to AI Tools

Most AI tools (Claude Desktop, Claude Code, etc.) need an HTTPS URL to reach your MCP server. Since the server runs on your local network, you'll need a tunnel to expose it.

Tailscale Funnel (Recommended)

Tailscale Funnel exposes a local port to the internet over HTTPS with no configuration:

tailscale funnel --bg 3000
# → https://your-machine.tail1234.ts.net

Set PUBLIC_URL in your .env to the resulting URL.

Cloudflare Tunnel

cloudflared tunnel --url http://localhost:3000

Securing the endpoint

A tunnel makes /mcp reachable by anyone who discovers the URL, so they can use the intervals.icu API key configured on the server (the key itself is never exposed to them). Set MCPAUTHTOKEN to a long random secret (openssl rand -hex 32) and every /mcp request requires Authorization: Bearer ; each client snippet below shows where the header goes. The secret also gates the detailed half of /health. Full details: operations.md.

Set it in .env alongside your API key; docker-compose.yml forwards it automatically.

AI Tool (Claude Desktop, Claude Code, etc.)
    │  HTTPS
HTTPS Tunnel (Tailscale / Cloudflare)
    │  HTTP (localhost:3000)
intervals-mcp Server (Docker / Bun)
    │  HTTPS
intervals.icu API

Client configuration

Shortened. The full README is on GitHub.