convez.ai
MCP ServerIntegração & APIsIntermediário
j2h4u

MCP Strava Coach

j2h4u/mcp-strava

Transforme seu agente de IA em treinador pessoal baseado em dados reais de Strava

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-strava

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
—
Issues abertas
38
Contribuidores
2

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

ToolUse it for
get_fitness_stateCurrent load, fitness, fatigue, form, acute:chronic workload ratio (ACWR), freshness, and model context.
list_workoutsRecent or filtered workouts with factual volume and intensity metrics.
get_workout_detailDetailed metrics for a specific workout id.
compare_periodsSide-by-side date-range comparison, optionally filtered by sport.
project_fitness_stateForward fitness-state projections for training-load scenarios.
get_training_aggregatesBucketed 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

SurfaceCommand or promptWhat it returns
CLI daily briefuv run python -m mcp_strava report dailyDaily facts for current state, recent workouts, 14-day load, sport mix, freshness, and read-model status.
CLI weekly digestuv run python -m mcp_strava weeklyWeekly load, volume, efficiency, sport breakdowns, current-week activities, and week-over-week trends.
MCP daily promptstrava_daily_training_briefA daily brief scenario backed only by factual MCP metrics.
MCP weekly promptstrava_weekly_training_digestA weekly digest scenario using period-comparison metrics.
MCP shoe watchdogstrava_shoe_mileage_watchdogShoe 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:

FieldValue
Application NameAny local name, for example mcp-strava
CategoryAny suitable category
Websitehttp://localhost
Authorization Callback Domainlocalhost

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:

PathPurpose
/srv/mcp-strava/data/strava.duckdbDuckDB mirror and read-model facts
/opt/docker/mcp-strava/.envStrava 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

Sport science & methodology — cardiac cost and cardiac drift are different metrics, tracked independently; see each file's scope note.

Project

Development

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.

Ver o original no GitHub

Bom para

Relacionados