🏃 intervals-icu-mcp

MCP Server untuk Intervals.icu

Hubungkan AI agent (Claude, Antigravity, atau MCP client lain) langsung ke data training Anda di Intervals.icu — activities, wellness, calendar, gear, power curves, dan custom items.

✨ Fitur

• 📊 Activities — Ambil daftar aktivitas, detail, interval splits, dan time-series streams (power, HR, cadence, pace)

• 💤 Wellness — Data harian HRV, resting HR, sleep score, CTL/ATL

• 📅 Calendar / Events — List, detail, hapus event, buat planned workout & catatan

• ⚙️ Gear — Katalog sepatu, sepeda, dan peralatan lain

• 📈 Power Curves — Best power per durasi (MMP)

• 🗂️ Custom Items — Baca, buat, update, dan hapus custom item

Related MCP server: fitness-mcp-server

🤖 Bonus: Running Coach AI (Template)

Project ini dilengkapi template Antigravity skill & workflow untuk membangun Running Coach AI personal berbasis data Intervals.icu Anda:

• /run-report — Slash-command untuk analisis pasca-sesi otomatis: tidak perlu upload CSV atau screenshot manual, data diambil langsung via MCP.

• running-coach-analysis — Skill yang berisi panduan analisis fisiologis (Aerobic Decoupling, Cardiac Drift, Efficiency Factor) dan format coaching report 4-bagian.

Lihat panduan konfigurasi di .agents/README.md.

🛠️ Tools (19)

Setiap tool menerima apiKey opsional (override per-call) dan sebagian besar menerima athleteId opsional (fallback ke INTERVALS_ATHLETE_ID).

🚀 Setup

1. Install & Build

pnpm install
pnpm run build

2. Konfigurasi Environment

Copy .env.example ke .env untuk testing lokal:

cp .env.example .env

Isi .env dengan kredensial Anda:

INTERVALS_API_KEY=your_api_key_here
INTERVALS_ATHLETE_ID=i123456

• INTERVALS_API_KEY: Wajib. Ambil dari Intervals.icu → Settings → Developer Settings.

• INTERVALS_ATHLETE_ID: Opsional. Jika kosong, wajib dikirim sebagai argumen athleteId di setiap tool call.

3. Konfigurasi MCP Client

Antigravity / Claude Desktop

Tambahkan ke MCP config Anda (mcp_config.json atau claude_desktop_config.json):

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/path/absolut/ke/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "your_api_key_here",
        "INTERVALS_ATHLETE_ID": "i123456"
      }
    }
  }
}

Restart client setelah edit config.

🔍 Debug Lokal

pnpm run inspector

Membuka MCP Inspector untuk mencoba tiap tool secara interaktif tanpa perlu connect ke client dulu.

📁 Struktur Project

intervals-icu-mcp/
├── src/
│   ├── index.ts          # Entry point, register semua tools, jalankan stdio transport
│   ├── config.ts         # Load environment variables
│   ├── client.ts         # HTTP client (Basic Auth, error handling)
│   ├── types.ts          # Helper convert ApiResult → CallToolResult
│   └── tools/
│       ├── activities.ts
│       ├── wellness.ts
│       ├── events.ts
│       ├── gear.ts
│       ├── powerCurves.ts
│       └── customItems.ts
├── .agents/              # Template Antigravity Agent konfigurasi (opsional)
│   ├── skills/running-coach-analysis/SKILL.md
│   └── workflows/run-report.md
├── .env.example
└── .gitignore

⚠️ Known Limitations

• Belum ada tool untuk athlete profile atau training zones secara langsung — bisa ditambah mengikuti pola yang sama di src/tools/.

• get_athlete_power_curves mengembalikan raw response dari API; parsing tambahan bisa dilakukan di sisi client.

• Belum ada rate-limit handling khusus di luar pesan error 429.

📚 Referensi API

• Base URL: https://intervals.icu/api/v1

• Auth: HTTP Basic Auth — username selalu API_KEY, password adalah API key Anda.

• Swagger Docs: https://intervals.icu/api-docs.html

Struktur endpoint di project ini juga diverifikasi dari mvilanova/intervals-mcp-server, MCP server intervals.icu versi Python.

📄 License

MIT