MCPacer
This MCP server lets Claude act as a running coach by connecting to Strava, managing training plans and persistent coaching memory, and using dashboard feedback tools.
Sync and retrieve Strava activities, date-range/recent queries, single-activity details, streams, and descriptions.
Add coaching feedback to Strava activity descriptions and persistent notes to runs.
Load detailed run summaries, find runs needing digestion, and save compact run digests.
Read active training-plan context, list/retrieve plans, edit workouts/weeks, add/remove runs, and annotate plans.
Load coaching personas and onboarding questions.
Read/update coach memory sections and manage session logs, including archived logs.
List body regions, read athlete-painted pain/tightness regions, and set/clear amber body-map highlights.
Provides tools to integrate with Strava, allowing retrieval of activities, run details, and posting coaching feedback to Strava activity descriptions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCPacer what's my training plan for next week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

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/mcpacerThis installs dependencies, registers the MCP server with Claude Code, and installs the /mcpacer coaching skill.
Launch
uv run mcpacerThis 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:
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 CoachWebsite:
http://localhostAuthorization Callback Domain:
localhost
Enter your credentials ā Paste the Client ID and Client Secret into the onboarding form
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:
Loads coach memory, run context, plan context, and session logs
Auto-loads your preferred persona
Digests any new runs
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 |
| Sync activities from Strava and return tiered training overview |
| Active plan as compact text with current week highlighted |
| List available persona names |
| Load a persona's full coaching guidelines |
| Load the onboarding questionnaire for a new athlete (PRs, goals, constraints) |
Coach Memory
Tool | Description |
| Load COACH_MEMORY.md (athlete knowledge, flags, patterns) |
| Rewrite a specific section in-place |
| Load recent session summaries (auto-distills older logs) |
| Write session summary at end of conversation |
Activities & Runs
Tool | Description |
| Get recent activities from Strava (paginated) |
| Get activities within a date range |
| Get a single activity by Strava ID |
| Get detailed data streams (pace, HR, altitude, cadence) |
| Formatted run summary with laps, HR, pace, elevation |
| Get runs needing digestion with pre-built prompts |
| Save a compact digest line for a run |
| Post coaching feedback to a Strava activity description |
| Add a coach note to a run (stored locally) |
Training Plans
Tool | Description |
| List all saved plans |
| Retrieve full plan YAML by ID |
| Modify a single workout |
| Update week-level metadata |
| Add a new workout to a week |
| Remove a workout from a week |
| 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 styleProject 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 skillsCLI 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 calendarUsing 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/mcpacerThen 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 toolsadd_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
Scored across 32 tools
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.
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.
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.
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
Related MCP Connectors
AI coach for Garmin: builds training plans and structured workouts, synced straight to your watch.
Running coach: your AI reads your runs and recovery, and writes sessions to your watch or phone.
Turn Claude or ChatGPT into a cycling coach that plans your week, grades it, and adapts. Free beta.
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
Related MCP Servers
- AlicenseAqualityDmaintenanceConnects Claude to your Strava account for analyzing training, predicting race times, and generating periodized training plans via natural language.13125 npmISC
- FlicenseNot gradedqualityBmaintenanceConnects Claude to Garmin Connect data for personalized running coaching, including morning readiness checks, post-run analysis, weekly reviews, and goal tracking.-
- AlicenseAqualityDmaintenanceConnects Strava training data to Claude, enabling personalized coaching through analysis of training load, workout planning, gear maintenance, and power metrics.1052 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceExposes your Strava data to Claude, enabling training load analysis, activity comparison, and lap splits via conversation.8 npmMIT