intervals-mcp

Intervals Extra (intervals-mcp)

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

All 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. Configuration is checked at startup: a bad variable stops the server with a message naming it, and the key's presence is 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, the newest release (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. :edge tracks unreleased main. Published images carry SBOM/provenance attestations you can verify; see operations.md.

GET /health reports liveness without spending an intervals.icu API request; with MCP_AUTH_TOKEN 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 MCP_AUTH_TOKEN to a long random secret (openssl rand -hex 32) and every /mcp request requires Authorization: Bearer <token>; 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

The server works with any MCP client that supports the Streamable HTTP transport. In every snippet below, replace https://your-public-url with your tunnel URL (or http://localhost:3000 for local development), and include the Authorization header only if you set MCP_AUTH_TOKEN.

Claude Desktop

Add to your Claude configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "intervals-mcp": {
      "type": "url",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

Restart Claude Desktop to load the new configuration.

Claude Code

claude mcp add --transport http intervals-mcp https://your-public-url/mcp \
  --header "Authorization: Bearer your-mcp-auth-token"

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "intervals-mcp": {
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

VS Code

Add to .vscode/mcp.json in your workspace (or run MCP: Add Server from the command palette):

{
  "servers": {
    "intervals-mcp": {
      "type": "http",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

Other clients (generic Streamable HTTP)

Any client that speaks Streamable HTTP can connect to the /mcp endpoint directly. The endpoint serves the 2026-07-28 revision: clients send stateless requests carrying the io.modelcontextprotocol/* envelope keys and the Mcp-Method/Mcp-Name headers (server/discover advertises capabilities). A 2025-era client (one that opens with initialize) is served statelessly too, because claude.ai loads MCP Apps that way, but it gets no write tool: update-activity, update-wellness and update-gear need a 2026-07-28 client. POST JSON-RPC messages with an Accept: application/json, text/event-stream header. Protocol details: docs/architecture.md.

Tools

The full tool catalog, prompts, permission behaviour, and example requests live in docs/tools.md. All text tools and every MCP App's data handler talk to intervals.icu directly.

Documentation

Doc	Contents
docs/tools.md	Full tool catalog, prompts, permission behaviour, example requests
docs/operations.md	Environment variables, the API key, health endpoint, rate limits, endpoint security
docs/architecture.md	Server architecture: transport, HTTP layer, cache, error taxonomy, analysis math
docs/api-notes.md	Calling the intervals.icu API: auth, endpoints, verified behaviour from Phases 1 and 2
docs/mcp-apps.md	MCP App packages: shared shell, mobile, theming, per-app details
docs/development.md	Monorepo mechanics: Turborepo, coverage gates, Storybook gates, Docker build
docs/releasing.md	Release automation: Conventional Commit PR titles, release-please, publishing
docs/project.md	Issue tracking and project board
docs/Intervals_MCP_Server.md	Capability reference to upload as project knowledge in a Claude project using this server

PRs are squash-merged and the PR title becomes the commit on main, so write it as a Conventional Commit (fix: patch, feat: minor, any ! or BREAKING CHANGE: footer major; chore:/docs:/refactor:/ci: release nothing). A CI check rejects non-conforming titles; see docs/releasing.md.

Troubleshooting

Server exits at startup: The message names the variable to fix, one line per bad variable. See operations.md.

AI tool can't reach the server — MCP requires an HTTPS URL. Use a tunnel (Tailscale Funnel or Cloudflare Tunnel) to expose your local server. See Connecting to AI Tools.

API key errors: Check /health first: api_key_configured tells you whether the server has a key set at all. If api_key_configured is true but calls still fail, the key may be wrong or revoked; generate a new one at intervals.icu, Settings, Developer Settings, and update INTERVALS_API_KEY. See operations.md.

Today's run is missing, or dates are a day off: Check time_zone and time_zone_source on /health. With TZ unset (or UTC), the server uses your intervals.icu time zone; set TZ to choose one. See operations.md.

"Cloudflare … answered with a challenge": Cloudflare, in front of intervals.icu, stopped the request before it reached intervals.icu, so this is not an API key problem. Wait a few minutes and retry. See operations.md.

Client can't connect (401 or unsupported protocol version): Each refused /mcp request writes one mcp_rejected line to the server log with its status, JSON-RPC code and, when the client sent it, its name. A 401 means the bearer token is missing or wrong. Code -32022 means the client's envelope names an MCP revision the server does not serve. See operations.md.

Is the server up and reachable? curl https://your-public-url/health. It answers without touching the intervals.icu API, so it works even when your rate limit is exhausted.

Client re-prompts for read tools after I granted them — A release likely renamed a tool or changed its input schema; grants are stored per tool identity, so that drops the grant. Releases say so in the changelog. Otherwise persistence lives in the client — check both connector-level and per-tool settings. See docs/tools.md.

License

MIT