MCP Strava Coach
j2h4u/mcp-strava
Transforme seu agente de IA em treinador pessoal baseado em dados reais de Strava
Ver no GitHubServidor MCP que conecta sua conta Strava a agentes de IA para análise avançada de treinos. Constrói um espelho local completo do seu histórico de treinos e fornece métricas preparadas como fitness, fadiga, forma, tendências de treino e projeções, funcionando até em contas Strava gratuitas.
Instalação
npx convez-ai j2h4u/mcp-strava1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Análise de padrões de treino e detecção de overtraining
- Comparação de períodos de treino e evolução mensal/semanal
- Projeção de fitness e simulação de cenários de carga de treino
- Relatórios automáticos de breve diário e digest semanal de treinos
- Consultas de métricas derivadas (TRIMP, ACWR, drift cardíaco, recuperação)
Veredito

MCP robusto e bem pensado que traz análise esportiva profissional sem dependência de Strava Pro. A construção local e reutilizável de métricas preparadas o distingue de conectores genéricos e o torna mais eficiente para agentes repetirem consultas.
README
A tradução para o português deste README ainda está na fila.
Coach's view of your training
Give an AI agent a coach's view of your training — over your own Strava data, even on a free Strava account.
mcp-strava connects your Strava account to an AI agent so it can act as your coach and sports physiologist: it reads your real training history and answers questions like "am I overtraining?", "how does this month compare to last?", or "what should this week look like?" — grounded in your actual workouts, not guesses.
It works with any Strava account, including the free tier. You bring your own Strava API credentials, so you don't need a paid Strava subscription to give an agent full read access to your training history.
What You Can Use It For
- Daily training brief: current fitness state, recent workouts, load, form, freshness, and notable data gaps.
- Weekly digest: weekly load, volume, efficiency, sport breakdowns, current-week workouts, and current-vs-previous week trends.
- Period comparison: compare two arbitrary date ranges across distance, training impulse (TRIMP), time, elevation, HR, cardiac cost, drift, recovery, and model-state metrics.
- Training trends: see how your training evolves over time — by day, week, month, year, or all-time, overall or per sport.
- Workout analysis: inspect one workout with factual intensity, heart-rate, drift, recovery, elevation, kudos, and gear facts when available.
- Fitness projection: simulate named load scenarios to see projected fitness, fatigue, and form through a target date.
Why Local
Instead of proxying every question to Strava on demand, mcp-strava builds a full local mirror of your Strava history and serves the agent from that. Once your supported history is mirrored, your training facts are queryable on your machine, repeatable across runs, and available for custom analysis without spending API quota on every prompt.
That choice gives you:
- A durable local copy of activities, streams, kudos, gear facts, and derived read-model facts.
- Fast historical questions, including daily, weekly, monthly, all-time, and per-sport aggregates.
- Reproducible metrics such as training impulse (TRIMP), fitness, fatigue, form, acute:chronic workload ratio (ACWR), cardiac drift, recovery, and sport-efficiency summaries.
How it compares to the official connector. Strava announced an official MCP connector for Claude on June 1, 2026, providing read-only access to training history, streams, GPS, power, clubs, and events — but it is rolling out to Strava subscribers. mcp-strava is the self-hosted alternative: it works on any account including the free tier, keeps a local mirror on your machine, and adds prepared aggregate bundles and CLI reports on top.
MCP Tools
| Tool | Use it for |
|---|---|
get_fitness_state | Current load, fitness, fatigue, form, acute:chronic workload ratio (ACWR), freshness, and model context. |
list_workouts | Recent or filtered workouts with factual volume and intensity metrics. |
get_workout_detail | Detailed metrics for a specific workout id. |
compare_periods | Side-by-side date-range comparison, optionally filtered by sport. |
project_fitness_state | Forward fitness-state projections for training-load scenarios. |
get_training_aggregates | Bucketed aggregate facts for dashboards, digests, and custom analysis. Ships prepared metric bundles for common views (daily brief, weekly digest, sport efficiency, and more). |
Ready-Made Reports
| Surface | Command or prompt | What it returns |
|---|---|---|
| CLI daily brief | uv run python -m mcp_strava report daily | Daily facts for current state, recent workouts, 14-day load, sport mix, freshness, and read-model status. |
| CLI weekly digest | uv run python -m mcp_strava weekly | Weekly load, volume, efficiency, sport breakdowns, current-week activities, and week-over-week trends. |
| MCP daily prompt | strava_daily_training_brief | A daily brief scenario backed only by factual MCP metrics. |
| MCP weekly prompt | strava_weekly_training_digest | A weekly digest scenario using period-comparison metrics. |
| MCP shoe watchdog | strava_shoe_mileage_watchdog | Shoe and gear mileage facts for replacement review. |
How It Works
- Mirrors Strava activities, streams, kudos, and gear facts into DuckDB.
- Materializes read-model facts for fast MCP tool calls.
- Returns freshness, completeness, warnings, and rationale with product responses so agents know what evidence they are using.
Requirements
- Python 3.14+
uv- Docker with Compose
just- A Strava API application for OAuth credentials
First-Time Strava Setup
This project stores Strava credentials in a local env file, not in a keychain. Treat this file as secret material and keep it outside git.
1. Create A Strava Application
Open https://www.strava.com/settings/api and create an application:
| Field | Value |
|---|---|
| Application Name | Any local name, for example mcp-strava |
| Category | Any suitable category |
| Website | http://localhost |
| Authorization Callback Domain | localhost |
Copy the generated Client ID and Client Secret.
2. Authorize The Application
Open this URL in a browser after replacing CLIENT_ID:
https://www.strava.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=http://localhost/exchange_token&response_type=code&approval_prompt=force&scope=read,activity:read_all,profile:read_all
After approval, Strava redirects to a localhost URL. The page may fail to load; that is fine. Copy the code query parameter from the browser address bar.
3. Exchange The Code For Tokens
curl -s -X POST https://www.strava.com/oauth/token \
-d client_id=CLIENT_ID \
-d client_secret=CLIENT_SECRET \
-d code=AUTHORIZATION_CODE \
-d grant_type=authorization_code
The response contains access_token, refresh_token, and expires_at.
4. Write The Token File
For local development, copy the tracked template and fill the values in .env:
cp .env.example .env
$EDITOR .env
chmod 600 .env
For the Docker runtime, the canonical token file is /opt/docker/mcp-strava/.env:
install -d -m 750 /opt/docker/mcp-strava
install -m 600 .env /opt/docker/mcp-strava/.env
Tokens refresh automatically. To verify credentials manually:
MCP_STRAVA_TOKEN_PATH=.env uv run python -m mcp_strava admin token-refresh
After the token file exists, routine token refresh and Strava rate-limit handling are automatic.
Local Docker Usage
just runtime
This builds the image, starts the mcp-strava container, waits for health, and runs a direct MCP smoke test against the product server at http://127.0.0.1:8080/mcp.
Configuration
A local run needs no configuration beyond your Strava credentials and resting heart rate. Server settings (paths, host/port, prompt language, refresh behavior, security allowlists) are environment variables with sensible defaults — see docs/tech/configuration.md.
Useful Commands
# Daily training brief
uv run python -m mcp_strava report daily
# Weekly digest
uv run python -m mcp_strava weekly
# Recent workouts
uv run python -m mcp_strava workouts recent --limit 10
# Analyze the latest workout
uv run python -m mcp_strava workout analyze latest
# Static quality gate: format, lint, types, imports, workflows, compile, dead code
just check
# Unit tests only
just unit
# Opt-in debt gate: type-check tests without making verify depend on it yet
just typecheck-tests
# Runtime validation: Docker build/start, MCP smoke
just runtime
# Full local validation before claiming completion
just verify
# Full MCP smoke against the running Docker service
just mcp-smoke-full
# Read-model latency gate
just mcp-read-model-perf
# List exposed MCP tools
just mcp-list-tools
Runtime State
Live Docker state is split — the DuckDB mirror lives under /srv (data separated from the deploy dir), the secret env stays beside the compose under /opt/docker:
| Path | Purpose |
|---|---|
/srv/mcp-strava/data/strava.duckdb | DuckDB mirror and read-model facts |
/opt/docker/mcp-strava/.env | Strava OAuth credentials + resting-HR (mounted with .env.lock) |
The mirror path is instance config, not source: override it with MCP_STRAVA_DATA_DIR in an untracked deploy/.env (default /srv/mcp-strava/data).
MCP Boundary
The MCP server is read-only and factual. It does not expose sync, admin, debug, raw SQL, token, or raw Strava API tools. Agents receive metrics and freshness facts, then perform their own interpretation.
Documentation
Usage
- Configuration — server environment variables and their defaults.
Operations
- Deployment runbook — gateway registration, DuckDB compaction, rollback, secret handling.
Reference
- Strava Kudos API field notes — endpoint behavior for kudos data.
Sport science & methodology — cardiac cost and cardiac drift are different metrics, tracked independently; see each file's scope note.
- Cardiac cost: cross-activity normalization research — why cardiac cost is tracked per sport, not normalized across activities.
- Cardiac drift: steady-state requirement — why decoupling needs a constant pace to be meaningful.
Project
- Contributing — contribution workflow.
- Agent & project notes — project context and constraints for AI coding agents.
- Commercial licensing — terms for commercial use.
Development
- Strava MCP skill definition — agent-facing tool/skill spec.
- Expert panel pattern — multi-expert review process used in this repo.
License
Copyright (c) 2026 Maksim Brashchenko.
This project is available for noncommercial use under the PolyForm Noncommercial License 1.0.0. Commercial use requires a separate written commercial license; see COMMERCIAL.md.