Skip to content

rashi283/mcp-fitness

Repository files navigation

Fitness Trainer MCP System

A Model Context Protocol (MCP) implementation for a personal fitness trainer AI that provides personalized workout plans, tracks user progress, and maintains safety-focused recommendations.

Overview

This system demonstrates how MCP can be used to create a sophisticated fitness trainer that:

  • Maintains user profiles with fitness levels, goals, and injury considerations
  • Tracks workout history and progress over time
  • Generates personalized workout plans based on safety rules and progression
  • Applies consistent fitness trainer personality and behavior protocols
  • Provides session memory across multiple interactions

Architecture

The system follows the technical flow you outlined:

Step 1: System Setup

  • FITNESS_TRAINER_PROTOCOL: Pre-loaded behavior rules and personality
  • EXERCISE_DATABASE: Exercise library with safety considerations and progressions
  • BEHAVIOR_RULES: Safety-first approach with injury considerations

Step 2-5: Request Processing

  • User makes request via MCP client
  • Server retrieves user profile and session history
  • Generates personalized response using protocol rules
  • Updates session memory with new information

Key Features

Safety-First Design

  • Always considers user injuries before suggesting exercises
  • Provides modifications for different fitness levels
  • Never recommends exercises that could worsen known injuries

Progressive Workout Generation

  • Analyzes previous workout feedback to determine difficulty progression
  • Builds on successful exercises while maintaining safety
  • Provides encouraging but realistic guidance

Session Memory

  • Maintains complete user profiles across sessions
  • Tracks workout history with feedback and duration
  • Uses historical data to inform future recommendations

Tools Provided

The MCP server provides these tools:

  1. get_user_profile(session_id) - Retrieve user profile and workout history
  2. create_user_session(session_id, name, fitness_level, goals, injuries, preferences) - Create new user profile
  3. add_workout_session(session_id, exercises_done, feedback, duration) - Record completed workouts
  4. generate_workout_plan(session_id, user_request) - Generate personalized workout plans
  5. get_fitness_protocol() - Get trainer behavior rules and protocol
  6. get_exercise_database() - Get available exercises and safety information

Example Workflow

The system demonstrates Sarah's fitness journey:

Initial Setup

{
  "name": "Sarah",
  "fitness_level": "Beginner", 
  "goals": ["lose weight", "build strength"],
  "injuries": ["lower back pain"],
  "preferences": ["home workouts", "no gym equipment"]
}

Workout History

  • June 15: Bodyweight squats, wall push-ups (20 min)
  • June 18: Squats, modified push-ups, planks (25 min)

Generated Workout Plan

Based on progress analysis, the system generates:

  1. Bodyweight squats: 15 reps (2 sets) - Progression from previous session
  2. Knee push-ups: 8 reps (2 sets) - Advancement from modified push-ups
  3. Glute bridges: 12 reps (2 sets) - Safe for back, builds strength
  4. Modified side planks: 20 seconds each side

Setup and Usage

Installation

pip3 install -r requirements.txt

Running the Demo

python3 fitness_mcp_client.py

This will demonstrate the complete workflow:

  1. Load fitness trainer protocol
  2. Create Sarah's user profile
  3. Add workout history
  4. Generate personalized workout plans
  5. Show progression over multiple sessions

Running the HTTP Server

python3 fitness_http_server.py

Testing the HTTP Flow

python3 test_http_flow.py

Expected Output

The demo shows how the system:

  • ✓ Creates user profile with safety considerations
  • ✓ Tracks workout history and progress
  • ✓ Generates personalized workouts based on injuries and progress
  • ✓ Applies fitness trainer protocol and behavior rules
  • ✓ Maintains session memory across interactions

Technical Implementation

Data Models

  • UserProfile: User information, fitness level, goals, injuries
  • WorkoutSession: Individual workout records with feedback
  • SessionMemory: Complete user session with profile and history

Safety Logic

  • Exercise database includes injury compatibility
  • Workout generation checks injury considerations
  • Progression logic based on feedback analysis

Response Formatting

  • Encouraging tone matching trainer personality
  • Structured workout plans with safety notes
  • Context-aware messaging based on progress

Files

  • fitness_mcp_server.py - Main MCP server with fitness trainer tools
  • fitness_mcp_client.py - Demo client showing complete workflow
  • fitness_http_server.py - HTTP server wrapper for API access
  • test_http_flow.py - Test script for HTTP request/response flow
  • mcp_config.json - MCP server configuration
  • requirements.txt - Python dependencies
  • README.md - This documentation

Extending the System

To add new features:

  1. New Exercises: Add to EXERCISE_DATABASE with safety considerations
  2. Additional Tools: Create new @mcp.tool() functions
  3. Enhanced Logic: Extend workout generation algorithms
  4. Database Integration: Replace mock storage with real database

Next Steps

This foundation can be extended with:

  • Real database integration (PostgreSQL, MongoDB)
  • More sophisticated progression algorithms
  • Integration with wearable devices
  • Video exercise demonstrations
  • Nutrition tracking and recommendations
  • Integration with actual AI assistants like Claude

The system demonstrates how MCP can create sophisticated, context-aware AI applications that maintain state, follow protocols, and provide personalized experiences.

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published