Skip to main content
Glama

MCPacer

Tests

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

Panel

What it shows

Plan Overview

Vertical bar chart of weekly mileage — planned (grey) vs actual (colored)

Week Detail

Day-by-day breakdown with prescribed and completed runs

Run Detail

GPS map, stats grid, workout analysis chart with proportional lap bars, splits table

Coach

Integrated terminal running Claude Code

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, davihh (meme-brained David parody). Create your own by adding a .md file.

Architecture

MCP Tools

The coach interacts with your data through these MCP tools:

Session Context

Tool

Description

get_run_context

Sync activities from Strava and return tiered training overview

get_plan_context

Active plan as compact text with current week highlighted

get_coaching_personas

List available persona names

get_coaching_persona

Load a persona's full coaching guidelines

get_onboarding_questions

Load the onboarding questionnaire for a new athlete (PRs, goals, constraints)

Coach Memory

Tool

Description

read_coach_memory

Load COACH_MEMORY.md (athlete knowledge, flags, patterns)

update_coach_memory

Rewrite a specific section in-place

get_session_logs

Load recent session summaries (auto-distills older logs)

save_session_log

Write session summary at end of conversation

Activities & Runs

Tool

Description

get_activities

Get recent activities from Strava (paginated)

get_activities_by_date_range

Get activities within a date range

get_activity_by_id

Get a single activity by Strava ID

get_activity_streams

Get detailed data streams (pace, HR, altitude, cadence)

get_run_detail

Formatted run summary with laps, HR, pace, elevation

get_pending_digests

Get runs needing digestion with pre-built prompts

save_run_digest

Save a compact digest line for a run

add_coaching_feedback

Post coaching feedback to a Strava activity description

add_run_note

Add a coach note to a run (stored locally)

Training Plans

Tool

Description

list_training_plans

List all saved plans

get_training_plan

Retrieve full plan YAML by ID

update_plan_run

Modify a single workout

update_plan_week

Update week-level metadata

add_plan_run

Add a new workout to a week

remove_plan_run

Remove a workout from a week

add_plan_comment

Document changes with a comment

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.

Available Tools

32 tools
add_coaching_feedbackA
    Add coaching feedback to a Strava activity description.

    Appends feedback from the coach to the activity's description,
    preserving any existing description text.

    IMPORTANT — pass ONLY the raw feedback body. Do NOT include:
      - a leading "(CoachName šŸ¤–)" prefix or any šŸ¤– emoji
      - a trailing "Coached by MCPacer …" signature
      - separator lines like "-------"
    The tool wraps your text with all of these automatically. If you
    copy the format you see in existing descriptions, you will produce
    duplicate emojis and a duplicate signature.

    Args:
        activity_id: ID of the activity to add feedback to
        feedback: The raw coaching feedback body (no prefix, no signature)
        coach_name: Name of the coach to display (default: "Coach")

    Returns:
        Dictionary with success status or error message
    

Inputs: feedback (required), activity_id (required), coach_name. Returns: object

add_plan_commentA
    Add a YAML comment to a week block. Documents plan adjustments
    in the plan itself (e.g. "Deload week — groin recovery, cut volume 30%").

    These comments persist through all future reads and exports.

    Args:
        plan_id: The plan ID.
        week_number: Which week.
        comment: The comment text (without # prefix).

    Returns:
        Confirmation message.
    

Inputs: comment (required), plan_id (required), week_number (required). Returns: result

add_plan_runA
    Add a new workout to a week.

    Args:
        plan_id: The plan ID.
        week_number: Which week.
        run_json: JSON string of the run to add.
            Example: {"day_of_week": "Friday", "type": "easy", "distance_km": 8, "description": "Recovery"}

    Returns:
        Confirmation message.
    

Inputs: plan_id (required), run_json (required), week_number (required). Returns: result

add_run_noteA
    Add a coach note to a cached run. Notes persist across sessions.

    Use this when the athlete shares context that changes interpretation
    of a run (treadmill paces, watch glitch, how they felt, etc.).
    Notes appear as šŸ“ lines in get_run_context() output.

    Args:
        activity_id: The Strava activity ID.
        note: The note text to append.

    Returns:
        Confirmation message.
    

Inputs: note (required), activity_id (required). Returns: result

clear_body_highlightsA
    Clear all amber highlights in the Body panel. Does NOT touch what
    the athlete has painted — only the agent-driven highlights.

    Returns:
        Confirmation.
    

Inputs: no named parameters. Returns: result

get_activitiesA
    Get the authenticated athlete's recent activities.

    Args:
        limit: Maximum number of activities to return (default: 10)

    Returns:
        Dictionary containing activities data
    

Inputs: limit. Returns: object

get_activities_by_date_rangeA
    Get activities within a specific date range.

    Args:
        start_date: Start date in ISO format (YYYY-MM-DD)
        end_date: End date in ISO format (YYYY-MM-DD)
        limit: Maximum number of activities to return (default: 30)

    Returns:
        Dictionary containing activities data
    

Inputs: end_date (required), start_date (required), limit. Returns: object

get_activity_by_idB
    Get detailed information about a specific activity.

    Args:
        activity_id: ID of the activity to retrieve

    Returns:
        Dictionary containing activity details
    

Inputs: activity_id (required). Returns: object

get_activity_descriptionA
    Get an activity's description to check for existing coaching feedback.

    Args:
        activity_id: ID of the activity

    Returns:
        Dictionary with activity id, name, and description
    

Inputs: activity_id (required). Returns: object

get_activity_streamsA
    Get stream data for a specific activity (e.g., heartrate, pace, altitude).

    Args:
        activity_id: ID of the activity to retrieve streams for
        stream_types: Comma-separated list of stream types to retrieve.
                     Available types: heartrate, pace, altitude, cadence, distance,
                     moving, temperature, time, watts (default: "heartrate,pace")

    Returns:
        Dictionary containing stream data indexed by stream type
    

Inputs: activity_id (required), stream_types. Returns: object

get_archived_session_logA
    Retrieve a full session log from the archive by date.

    Older session logs are automatically compressed into one-liners in
    the Session History section of coach memory. Use this tool when a
    one-liner doesn't provide enough context and you need the full
    original session summary.

    Args:
        session_date: Date of the session in YYYY-MM-DD format.

    Returns:
        The full session log text, or a message if not found.
    

Inputs: session_date (required). Returns: result

get_coaching_personaA
    Load a coaching persona's full definition and guidelines.

    Returns the persona's personality, tone, and communication style
    combined with shared coaching guidelines. This content should be
    adopted fully for the duration of the session.

    Args:
        coach_name: Name of the coach persona to load (e.g. "david", "coach").

    Returns:
        The full persona text as markdown.
    

Inputs: coach_name (required). Returns: object

get_coaching_personasA
    Get the list of available coaching personas.

    Returns:
        Dictionary containing a list of available coach names.
    

Inputs: no named parameters. Returns: object

get_onboarding_questionsA
    Load the onboarding questionnaire for a new athlete.

    Call this when read_coach_memory returns "not been onboarded yet" or
    the Athlete section of coach memory is empty. Returns the full series
    of questions to ask (PRs, goals, constraints, etc.) plus instructions
    for saving initial memory and drafting a training plan.

    Returns:
        Dictionary with the onboarding questionnaire as markdown.
    

Inputs: no named parameters. Returns: object

get_painted_regionsA
    Read the body regions the athlete has painted/marked on the body
    diagram. These are areas the athlete is reporting pain, tightness,
    or concern. Call this when the athlete refers to "what I've marked",
    "this area", or "where it hurts" — or proactively to check whether
    anything has been flagged.

    Returns:
        A list of painted region IDs with their human labels, or a
        note that nothing is painted.
    

Inputs: no named parameters. Returns: result

get_pending_digestsA
    Get runs that need LLM digestion, with pre-built prompts.

    Returns a list of items, each with activity_id, name, date, and the
    digestion prompt. The host should process each item — ideally by
    spawning parallel Haiku subagents — and save results via
    save_run_digest(activity_id, digest).

    Returns:
        Dict with "pending" list (each item has activity_id, name, date,
        prompt) or "message" if nothing is pending.
    

Inputs: no named parameters. Returns: object

get_plan_contextA
    Get the active training plan rendered as compact text.

    Returns a two-line-per-week overview with the current week highlighted.
    If no active plan exists, returns a message saying so — the coach
    works fine without a plan (off-season, casual running, etc.).

    Returns:
        Pre-formatted plan overview text.
    

Inputs: no named parameters. Returns: result

get_recent_activitiesB
    Get activities from the past X days.

    Args:
        days: Number of days to look back (default: 7)
        limit: Maximum number of activities to return (default: 10)

    Returns:
        Dictionary containing activities data
    

Inputs: days, limit. Returns: object

get_run_contextA
    Sync new activities from Strava and return a training overview.

    This is the primary tool for loading the athlete's training history
    at session start. It:
    1. Syncs any new activities from Strava
    2. Renders an age-tiered text snapshot (one-liners for older weeks,
       per-run detail for recent weeks)

    The output is purely actual run data — no plan awareness. The plan
    context is loaded separately via get_plan_context().

    Returns:
        Pre-formatted text block with the full training overview.
    

Inputs: no named parameters. Returns: result

get_run_detailA
    Get a detailed view of a single run — full lap splits, HR, elevation,
    digest, and coach notes. Use for post-race analysis, anomalies, or
    when the athlete asks about specific splits.

    Args:
        activity_id: The Strava activity ID.

    Returns:
        Formatted run detail as text.
    

Inputs: activity_id (required). Returns: result

get_session_logsA
    Read recent daily session logs — summaries of previous coaching conversations.

    Each log records what was discussed, flags raised, decisions made, and
    plan adjustments from a past session. Provides conversation continuity.

    Args:
        limit: Number of recent logs to return (default 3, max 5).

    Returns:
        Concatenated session logs as text, most recent first.
    

Inputs: limit. Returns: result

get_training_planA
    Get the full YAML content of a training plan.

    Use this when you need to inspect or edit individual workouts.
    For the compact overview, use get_plan_context() instead.

    Args:
        plan_id: The plan ID.

    Returns:
        Raw YAML content as text.
    

Inputs: plan_id (required). Returns: result

highlight_body_regionsA
    Highlight one or more body regions in the dashboard's Body panel
    (shown amber). Use this to draw the athlete's attention to a chain
    of related structures, suggest "is this what hurts?", or visualize
    the kinematic chain you're reasoning about.

    Calling this REPLACES the previous highlight set (it is not
    additive). To wipe, pass an empty list or call clear_body_highlights.

    Args:
        regions: List of region IDs (use list_body_regions to discover
                 valid IDs). Invalid IDs are silently dropped.
        reason: Short caption explaining why these are highlighted —
                shown to the athlete in the panel (e.g.
                "checking IT band kinematic chain").

    Returns:
        Confirmation with the regions actually highlighted.
    

Inputs: regions (required), reason. Returns: result

list_body_regionsA
    List all valid body region IDs that can be highlighted on the body
    diagram or that the athlete might paint as a source of pain or
    tightness. Use this to discover region IDs before calling
    highlight_body_regions.

    Each region has a stable ID (e.g. left_itb_lower) and a human-
    readable label (e.g. "IT band — lower (L)"). Regions are grouped
    by body area.

    Returns:
        Grouped list of region IDs and labels.
    

Inputs: no named parameters. Returns: result

list_training_plansA
    List all saved training plans with summary metadata.

    Returns:
        Dict with plans list (id, name, race_date, goal_time, weeks count).
    

Inputs: no named parameters. Returns: object

read_coach_memoryA
    Read the full COACH_MEMORY.md — the coach's long-term knowledge about the athlete.

    Contains sections: Athlete, PRs, Goals, Active Flags, Training Context, Patterns & Insights.
    This is loaded at session start and can be re-read on demand.

    Returns:
        The full coach memory as markdown text.
    

Inputs: no named parameters. Returns: result

remove_plan_runB
    Remove a workout from a week.

    Args:
        plan_id: The plan ID.
        week_number: Which week.
        day_of_week: Day name (e.g. "Thursday").

    Returns:
        Confirmation message.
    

Inputs: plan_id (required), day_of_week (required), week_number (required). Returns: result

save_run_digestA
    Save a digest for a run (generated by LLM or host).

    Called after processing a digestion prompt from get_pending_digests().
    The digest should be a single compact line with segments separated
    by | (e.g. "WU 2km @5:00 | 10Ɨ1km @3:45 HR 165→185 | CD 2km | +110m").

    Args:
        activity_id: The Strava activity ID.
        digest: The digest string.

    Returns:
        Confirmation message.
    

Inputs: digest (required), activity_id (required). Returns: result

save_session_logA
    Save a session summary log for today.

    Called at the end of a coaching session to persist what was discussed.
    The summary should be 3-5 lines covering: what was discussed, flags
    raised, decisions made, and any plan adjustments.

    IMPORTANT: The first line should be a standalone sentence capturing
    the session's most important takeaway, as it will be used as a
    one-liner in compressed session history.

    Args:
        summary: The session summary text (3-5 lines).
        coach_name: Name of the coach persona used in this session.

    Returns:
        Confirmation message.
    

Inputs: summary (required), coach_name. Returns: result

update_coach_memoryA
    Update a specific section of the coach's memory (COACH_MEMORY.md).

    Rewrites the section in-place. Call this immediately when significant
    new information emerges — don't wait until session end.

    Sections:
        athlete — name, location, weight
        prs — self-reported PRs with date assessed
        goals — target race, current phase
        active_flags — injuries, niggles, concerns
        training_context — weekly volume, training days, constraints
        patterns — observations about the athlete's training

    Args:
        section: Section key (athlete, prs, goals, active_flags, training_context, patterns)
        content: New content for the section (replaces everything under the ## header)

    Returns:
        Confirmation message.
    

Inputs: content (required), section (required). Returns: result

update_plan_runA
    Modify a single workout within a week. Surgical edit — only the
    specified fields are changed, everything else is preserved.

    Args:
        plan_id: The plan ID.
        week_number: Which week (1-indexed).
        day_of_week: Day name (e.g. "Tuesday", "Sunday").
        updates_json: JSON string of fields to update.
            Example: {"type": "easy", "distance_km": 10, "description": "Recovery run"}

    Returns:
        Confirmation message.
    

Inputs: plan_id (required), day_of_week (required), week_number (required), updates_json (required). Returns: result

update_plan_weekB
    Update week-level metadata (weekly_focus, total_planned_distance_km, etc.).

    Args:
        plan_id: The plan ID.
        week_number: Which week.
        updates_json: JSON string of week-level fields to update.
            Example: {"weekly_focus": "Deload week", "total_planned_distance_km": 50}

    Returns:
        Confirmation message.
    

Inputs: plan_id (required), week_number (required), updates_json (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 32 tools

    Disambiguation4/5

    Most tools have distinct purposes, but the activity retrieval set (get_activities, get_activities_by_date_range, get_recent_activities) overlaps, and get_run_context versus get_plan_context could cause confusion. Overall, the boundaries are clear for the majority.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., add_*, get_*, list_*, update_*, clear_*, save_*). No mixing of styles or inconsistent verbs.

    Tool Count4/5

    32 tools is on the higher side but still appropriate for the breadth of functionality (activities, plans, body regions, memory, session logs, digestion). Each tool serves a distinct purpose, and the count is manageable.

    Completeness4/5

    The surface covers core coaching workflows: activity retrieval, plan CRUD, body diagram interaction, memory, session logs, and digestion. Minor gaps exist (e.g., no delete plan or remove comment tool), but the set is largely complete for the domain.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers