MCPacer

An AI-powered running coach that connects Claude to your Strava data through the Model Context Protocol (MCP). Get personalized training plans, track your progress, and receive coaching feedback — all through a web dashboard with an integrated coaching terminal. Currently, it has only been tested on Ubuntu.

⚠️ Use at your own risk. This is supposed to be a fun gadget to mess around with. That being said, I am only a hobby jogger, and it does run on top of claude code so if it messes up your computer or gets you injured it is not my fault. So take care, but also do have fun with it! I initially developped this to learn about MCP servers, and coach myself to a sub-3 hour marathon (https://www.strava.com/activities/17976045034) in a 14-ish week build starting from a 3:11:02 PR. We refined this repo during the CSAIL Agentic AI Hackathon 2026 to make it easier to use by adding UI features, a new experimental S&C tab, and improving the coaching workflow. Happy running 🤠

Pete

P.S. I can highly recommend coach David or coach Kim

Features

• Customizable Personas — Choose from multiple coaching styles (tough love, balanced, analytical, etc.)

• Web Dashboard — Plan overview, weekly breakdown, run detail with GPS maps and workout analysis charts

• Integrated Coaching Terminal — Chat with your AI coach directly in the dashboard

• Training Plans — Create, track, and adjust structured plans in YAML format

• Strava Sync — Automatically pull activities, laps, HR, pace, and GPS data

• Plan Adherence — Visual comparison of planned vs actual weekly mileage

• Persistent Memory — Coach remembers your goals, injuries, patterns, and session history across conversations. This enables periodization.

• Run Digestion — Each run gets a compact single-line summary for efficient context loading

• Body Map (PT mode) — Discuss imbalances, pain, and tightness directly with your coach to devise a strength and conditioning plan.

Related MCP server: Garmin Coach MCP

Getting Started

Prerequisites

• Python 3.12+

• UV — Python package manager

• Node.js 18+ — Required for the web frontend (includes npm)

Install

git clone https://github.com/wernerpe/mcpacer.git
cd mcpacer
uv sync
claude mcp add strava -- uv run --directory $(pwd) mcpacer-server
cp -r skills/mcpacer ~/.claude/skills/mcpacer

This installs dependencies, registers the MCP server with Claude Code, and installs the /mcpacer coaching skill.

Launch

uv run mcpacer

This starts both the FastAPI backend and SvelteKit frontend, then opens your browser. On first launch you'll see the onboarding screen.

Onboarding

The onboarding screen walks you through connecting to Strava:

1. Create a Strava API app — Go to developers.strava.com/docs/getting-started (Section B) and create an app with:

   • Application Name: My Strava Running Coach

   • Website: http://localhost

   • Authorization Callback Domain: localhost

2. Enter your credentials — Paste the Client ID and Client Secret into the onboarding form

3. Authorize — Click "Connect to Strava", approve in the popup, and you're in

Credentials and tokens are stored locally in .env and never leave your machine.

How It Works

Coaching Sessions

Run /mcpacer in the coaching terminal. The skill handles everything automatically:

1. Loads coach memory, run context, plan context, and session logs

2. Auto-loads your preferred persona

3. Digests any new runs

4. Opens the conversation

The coach reviews your training and responds based on your plan, recent activity, and history:

How's that groin feeling? And are we sticking to the dress rehearsal plan tomorrow or are you going to "freestyle" it again?

Accountability is everything in training. The coach posts directly to your Strava activity descriptions. Feedback is concise, references the plan, and focuses on what matters:

Plan said 4x1km @ 3:55. You did 6x1km @ 3:39. That's 50% more volume and 16s/km faster than prescribed — in f***ing taper week. The hay is in the barn. Stop setting the damn barn on fire. I can't believe this.

Dashboard Panels

All panel dividers are draggable (VS Code-style).

Training Plans

Plans are YAML files in training_plans/. The coach can create, modify, and track plans through MCP tools. Example structure:

plan_name: Sub-3 Marathon Build
goal_race:
  date: 2026-04-04
  goal_time: "2:59:59"
weeks:
  - week_number: 1
    total_planned_distance_km: 75
    runs:
      - day_of_week: Wednesday
        type: workout
        distance_km: 16
        structure: "2.5km warmup, 5x2km @ 3:50-3:55, cooldown"

Coaching Personas

Personas live in coaching_data/personas/ as markdown files. Each defines a coaching style, tone, and behavioral rules. Available: coach (balanced), david (tough love), roland, kim, hartmann. Create your own by adding a .md file.

Architecture

MCP Tools

The coach interacts with your data through these MCP tools:

Session Context

Coach Memory

Activities & Runs

Training Plans

Memory & Context

Every session starts fresh — no conversation history carries over. All continuity comes from structured context loaded at session start:

SESSION CONTEXT (~4000 tokens)
├── Coach Memory .............. ~600 tok
│   Long-term athlete knowledge: goals, PRs, injuries, patterns
│   └── Session History (one-liners for older sessions)
├── Run Context ............... ~1400 tok
│   Tiered by age: one-liners for old weeks, full detail for recent
├── Plan Context .............. ~1100 tok
│   Day-by-day prescriptions, current week highlighted
├── Session Logs .............. ~200 tok
│   Last 3 session summaries for conversation continuity
└── Persona ................... ~500 tok
    Coaching tone, personality, communication style

Project Structure

mcpacer/
├── src/mcpacer/
│   ├── server.py           # MCP server entry point
│   ├── strava_client.py    # Strava API client
│   ├── tools/              # MCP tool implementations
│   ├── storage/            # Run and plan persistence
│   ├── web/
│   │   ├── app.py          # FastAPI app (REST + WebSocket)
│   │   ├── api.py          # Dashboard REST endpoints
│   │   ├── auth.py         # Strava OAuth flow
│   │   ├── pty_manager.py  # Claude Code PTY management
│   │   └── launcher.py     # Starts backend + frontend
│   └── cli/                # CLI commands
├── web/                    # SvelteKit frontend
│   └── src/
│       ├── routes/         # Page routes
│       └── lib/            # Svelte components
├── coaching_data/          # Personas (tracked), memory (gitignored)
├── training_plans/         # Plan YAML files (gitignored)
├── run_data/               # Cached Strava data (gitignored)
└── skills/                 # Claude Code skills

CLI Commands

uv run mcpacer                   # Launch the web dashboard
uv run mcpacer-update-data       # Sync run data from Strava
uv run mcpacer-analyze-plan      # Analyze plan adherence
uv run mcpacer-generate-calendar # Generate HTML training calendar

Using as MCP Server Only

If you prefer to use the coaching tools without the web dashboard (e.g., in Claude Desktop):

claude mcp add strava -- uv run --directory /path/to/mcpacer mcpacer-server
cp -r /path/to/mcpacer/skills/mcpacer ~/.claude/skills/mcpacer

Then start a coaching session with /mcpacer in any Claude Code conversation.

Acknowledgements

This project started with a lot of inspiration from strava-mcp-server by Tomek Korbak.

License

MIT License — see LICENSE for details.