Health & Fitness Coach MCP 💪

🎯 What is this Project?

Health & Fitness Coach MCP is a comprehensive AI-powered fitness tracking application that bridges the gap between traditional fitness apps and intelligent AI assistance through the Model Context Protocol (MCP).

This project consists of two main components:

1. 🌐 Web Application: A modern Next.js fitness dashboard for logging activities and tracking progress
2. 🤖 MCP Server: A protocol-compliant server that enables AI tools (Cursor, Claude Desktop, etc.) to interact with your fitness data intelligently

🏗️ System Architecture & MCP Integration

┌─────────────────────────────────────────────────────────────────────────────┐
│                    HEALTH & FITNESS COACH ECOSYSTEM                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────┐  │
│  │   🌐 WEB APP        │    │   🤖 MCP SERVER     │    │  🧠 AI CLIENTS  │  │
│  │   (Next.js)         │    │   (Protocol Layer)  │    │  (Cursor/Claude) │  │
│  │                     │    │                     │    │                 │  │
│  │ • Fitness Dashboard │◄──►│ • 7 Smart Tools     │◄──►│ • Natural Lang  │  │
│  │ • Activity Logging  │    │ • Data Processing   │    │ • Context Aware │  │
│  │ • Progress Tracking │    │ • Context Analysis  │    │ • Plan Generate │  │
│  │ • Plan Visualization│    │ • API Integration   │    │ • Smart Queries │  │
│  │ • Real-time Updates │    │ • Protocol Compliance│   │ • Tool Calling  │  │
│  └─────────────────────┘    └─────────────────────┘    └─────────────────┘  │
│           │                           │                           │          │
│           └───────────────────────────┼───────────────────────────┘          │
│                                       │                                      │
│  ┌─────────────────────────────────────▼─────────────────────────────────────┐ │
│  │                     📊 UNIFIED DATA LAYER                               │ │
│  │                                                                         │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │ │
│  │  │ 🏋️ Workouts │  │ 🍎 Nutrition │  │ 📋 Plans    │  │ 💭 Feedback │   │ │
│  │  │ • Sessions  │  │ • Meals      │  │ • AI-Gen    │  │ • Progress  │   │ │
│  │  │ • Duration  │  │ • Calories   │  │ • Weekly    │  │ • Notes     │   │ │
│  │  │ • Types     │  │ • Items      │  │ • Daily     │  │ • Insights  │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │ │
│  └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

🤖 What is the MCP Server and Why It Matters?

Model Context Protocol (MCP) Explained

The Model Context Protocol is a standardized way for AI applications to connect to external data sources and tools. Think of it as a universal translator that allows AI assistants like Claude Desktop or Cursor to understand and interact with your fitness data.

MCP Server Role in This Application

Our MCP server acts as an intelligent fitness data gateway that:

1. 🔗 Bridges AI and Fitness Data

   • Translates natural language fitness queries into structured data operations
   • Enables AI tools to read, write, and analyze your fitness information
   • Provides context-aware responses based on your actual fitness history

2. 🧠 Enables Intelligent Coaching

   • AI can ask: "What workouts did I do this week?" → MCP fetches and analyzes your data
   • AI can suggest: "Create a workout plan" → MCP generates personalized routines
   • AI can track: "Log my 30-minute run" → MCP stores and updates your progress

3. 📊 Provides Rich Context

   • When you ask AI for fitness advice, it has access to your complete history
   • AI can identify patterns, suggest improvements, and track long-term progress
   • Enables personalized coaching based on your actual performance data

🛠️ MCP Server Tools & Capabilities

The MCP server exposes 7 intelligent tools that transform how AI interacts with fitness data:

Core Logging Tools

log-workout - Exercise Session Tracking

// What it does: Records workout sessions with intelligent categorization
{
  tool: "log-workout",
  parameters: {
    userId: "user123",
    date: "2025-01-07", 
    type: "strength training", // Auto-categorized: cardio, strength, flexibility
    duration: 45,              // Minutes of activity
    distance: 0                // Optional for cardio workouts
  }
}
// AI Context: "I did 45 minutes of strength training today"

log-nutrition - Meal & Calorie Tracking

// What it does: Logs meals with smart nutritional analysis
{
  tool: "log-nutrition", 
  parameters: {
    userId: "user123",
    date: "2025-01-07",
    meal: "breakfast",                    // Auto-detected: breakfast/lunch/dinner/snack
    items: ["oatmeal", "banana", "almonds"], // Natural language food items
    calories: 350                         // Calculated or estimated
  }
}
// AI Context: "I had oatmeal with banana and almonds for breakfast"

log-feedback - Progress & Motivation Tracking

// What it does: Captures subjective fitness experiences and progress notes
{
  tool: "log-feedback",
  parameters: {
    userId: "user123", 
    date: "2025-01-07",
    notes: "Feeling stronger after consistent workouts. Ready for heavier weights!"
  }
}
// AI Context: Tracks motivation, energy levels, and subjective progress

Intelligence & Planning Tools

generate-plan - AI-Powered Fitness Planning

// What it does: Creates personalized workout and nutrition plans
{
  tool: "generate-plan",
  parameters: {
    userId: "user123"
  }
}
// AI Magic: Analyzes your history, preferences, and goals to create:
// - Tomorrow's workout routine
// - Weekly exercise schedule  
// - Meal recommendations
// - Progressive difficulty adjustments

view-context - Comprehensive Fitness Analysis

// What it does: Provides complete fitness profile for AI decision-making
{
  tool: "view-context", 
  parameters: {
    userId: "user123"
  }
}
// Returns: Complete fitness history, patterns, goals, and insights
// Enables AI to make informed coaching decisions

set-weekly-target - Goal Setting & Tracking

// What it does: Establishes and tracks fitness goals
{
  tool: "set-weekly-target",
  parameters: {
    userId: "user123",
    weekStart: "2025-01-06", 
    targetRuns: 3,           // Weekly cardio goal
    calorieBudget: 2000      // Daily calorie target
  }
}
// AI Context: Enables goal-oriented coaching and progress tracking

Utility Tools

echo - System Health & Testing

// What it does: Tests MCP connectivity and system health
{
  tool: "echo",
  parameters: {
    message: "Testing MCP connection"
  }
}
// Usage: Debugging and ensuring MCP server is responsive

🔄 MCP Data Flow & AI Integration

How AI Queries Become Fitness Actions

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MCP DATA FLOW                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  User in AI Tool: "I did 20 push-ups for 15 minutes today"                 │
│         │                                                                   │
│         ▼                                                                   │
│  ┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────┐  │
│  │   🧠 AI PROCESSING  │    │   🤖 MCP PROTOCOL   │    │  📊 DATA STORE  │  │
│  │                     │    │                     │    │                 │  │
│  │ • Parse intent      │───►│ • Tool selection    │───►│ • Store workout │  │
│  │ • Extract data      │    │ • Parameter mapping │    │ • Update stats  │  │
│  │ • Choose action     │    │ • Execute tool call │    │ • Calculate     │  │
│  │ • Format response   │◄───│ • Return results    │◄───│   progress      │  │
│  └─────────────────────┘    └─────────────────────┘    └─────────────────┘  │
│         │                                                                   │
│         ▼                                                                   │
│  AI Response: "Great! I've logged your 15-minute push-up session.           │
│               You're at 15/60 minutes for your daily workout goal."         │
└─────────────────────────────────────────────────────────────────────────────┘

Web App ↔ MCP Server Integration

┌─────────────────────────────────────────────────────────────────────────────┐
│                        DUAL-INTERFACE SYSTEM                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────┐                    ┌─────────────────────┐         │
│  │   🌐 WEB INTERFACE  │                    │  🤖 AI INTERFACE    │         │
│  │                     │                    │                     │         │
│  │ • Visual dashboard  │                    │ • Natural language  │         │
│  │ • Click logging     │                    │ • Context queries   │         │
│  │ • Progress charts   │                    │ • Smart planning    │         │
│  │ • Plan display     │                    │ • Pattern analysis  │         │
│  └─────────────────────┘                    └─────────────────────┘         │
│           │                                           │                     │
│           ▼                                           ▼                     │
│  ┌─────────────────────────────────────────────────────────────────────────┐ │
│  │                     🔄 MCP SERVER CORE                                 │ │
│  │                                                                         │ │
│  │  • Unified data access for both interfaces                             │ │
│  │  • Consistent business logic and validation                            │ │
│  │  • Real-time synchronization between web and AI                        │ │
│  │  • Intelligent caching and performance optimization                    │ │
│  └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

🎯 Real-World Usage Scenarios

Scenario 1: Daily Workout Logging

👤 User in Cursor: "I just finished a 30-minute HIIT workout"

🤖 AI + MCP Process:
1. AI recognizes workout logging intent
2. MCP calls `log-workout` tool
3. Stores: type="HIIT", duration=30, date=today
4. Updates daily progress counters
5. AI responds with encouragement and progress update

📱 Web App: Automatically shows updated workout minutes and exercise completion

Scenario 2: Intelligent Plan Generation

👤 User in Claude: "Create a workout plan for tomorrow based on what I did this week"

🤖 AI + MCP Process:
1. MCP calls `view-context` to analyze week's activities
2. AI identifies patterns: mostly upper body, low cardio
3. MCP calls `generate-plan` with context
4. Creates balanced plan emphasizing legs and cardio
5. Stores plan for tomorrow

📱 Web App: Tomorrow's workout section populates with AI-generated exercises

Scenario 3: Nutrition Guidance

👤 User in AI: "I'm trying to eat healthier, what should I have for lunch?"

�� AI + MCP Process:
1. MCP calls `view-context` to check today's meals and calorie goals
2. AI analyzes nutritional gaps and calorie budget
3. Suggests specific meal with calorie count
4. User confirms: "I'll have the grilled chicken salad"
5. MCP calls `log-nutrition` to record the meal

📱 Web App: Updates nutrition progress and meal history

🌟 Key Benefits of MCP Integration

For Users

• 🎯 Personalized AI Coaching: AI has complete context of your fitness journey
• 💬 Natural Interaction: Talk to AI in plain English about fitness goals
• 📊 Intelligent Insights: AI can identify patterns and suggest improvements
• 🔄 Seamless Experience: Data syncs between web app and AI tools automatically

For Developers

• 🔌 Protocol Compliance: Standard MCP implementation works with any MCP client
• 🛠️ Extensible Architecture: Easy to add new tools and capabilities
• 📈 Rich Context: AI tools get comprehensive fitness data for better decisions
• 🔧 Flexible Deployment: Works with Cursor, Claude Desktop, or custom AI tools

For AI Applications

• 🧠 Domain Expertise: Specialized fitness knowledge and data processing
• 📋 Structured Data: Clean, organized fitness information for analysis
• ⚡ Real-time Updates: Live data synchronization for current information
• 🎨 Rich Responses: Contextual, personalized fitness coaching responses

🚀 Quick Start Guide

1. Set Up the MCP Server

git clone https://github.com/your-username/health-fitness-coach-mcp.git
cd health-fitness-coach-mcp
npm install
cp env.example .env.local
# Add OPENAI_API_KEY for AI-generated plans
npm run dev

2. Connect to AI Tools

Cursor Configuration

{
  "mcpServers": {
    "health-fitness-coach": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Claude Desktop Configuration

{
  "mcpServers": {
    "health-fitness-coach": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

3. Test the Integration

# Test MCP tools directly
npm run test:fitness

# Test specific endpoints
curl http://localhost:3000/api/context?userId=default-user

4. Start Using

• Web App: Visit http://localhost:3000 for visual fitness tracking
• AI Integration: Ask your AI assistant fitness-related questions
• Natural Language: "Log my workout", "Create a plan", "How am I doing?"

🔧 Technical Implementation Details

MCP Protocol Compliance

// MCP-compliant tool definition
export const logWorkoutTool = {
  name: "log-workout",
  description: "Log a workout session with type, duration, and optional distance",
  inputSchema: {
    type: "object",
    properties: {
      userId: { type: "string", description: "Unique user identifier" },
      date: { type: "string", description: "Date in YYYY-MM-DD format" },
      type: { type: "string", description: "Workout type (e.g., 'running', 'strength')" },
      duration: { type: "number", description: "Duration in minutes" },
      distance: { type: "number", description: "Distance in kilometers (optional)" }
    },
    required: ["userId", "date", "type", "duration"]
  }
}

Data Storage & Retrieval

// In-memory stores with persistence hooks
export const workoutStore = createInMemoryStore<WorkoutEntry>()
export const nutritionStore = createInMemoryStore<NutritionEntry>()
export const planStore = createInMemoryStore<PlanEntry>()

// MCP tool implementation
export async function logWorkout(params: LogWorkoutParams) {
  const entry: WorkoutEntry = {
    id: generateId(),
    userId: params.userId,
    date: params.date,
    type: params.type,
    duration: params.duration,
    distance: params.distance,
    timestamp: new Date().toISOString()
  }
  
  workoutStore.set(entry.id, entry)
  return { success: true, entry }
}

AI Integration Layer

// Chat interface with MCP integration
export async function processFitnessQuery(message: string, userId: string) {
  const intent = detectIntent(message)
  
  switch (intent.type) {
    case 'log_workout':
      return await callMCPTool('log-workout', {
        userId,
        date: intent.date,
        type: intent.workoutType,
        duration: intent.duration
      })
      
    case 'generate_plan':
      return await callMCPTool('generate-plan', { userId })
      
    case 'view_progress':
      return await callMCPTool('view-context', { userId })
  }
}

🧪 Testing & Development

Available Test Scripts

# Test all MCP tools
npm run test:fitness

# Test HTTP transport
npm run test:http

# Test MCP integration
npm run test:mcp

# Debug tool functionality  
npm run debug:tools

MCP Tool Testing

// Test workout logging
const result = await mcpClient.callTool('log-workout', {
  userId: 'test-user',
  date: '2025-01-07',
  type: 'running',
  duration: 30,
  distance: 5.0
})

console.log('Workout logged:', result)

🚀 Deployment Options

Local Development

• Run npm run dev for development server
• MCP server available at http://localhost:3000/mcp
• Web interface at http://localhost:3000

Production Deployment

• Deploy to Vercel with one-click button
• Configure environment variables (OPENAI_API_KEY)
• MCP server automatically available at your domain

Custom Deployment

• Docker support for containerized deployment
• Environment variable configuration for different setups
• Scalable architecture for multiple users

🔧 Environment Configuration

Required Variables

# OpenAI API key for AI-generated fitness plans
OPENAI_API_KEY=your_openai_api_key_here

# Optional Redis for enhanced performance
UPSTASH_REDIS_REST_URL=your_redis_url
UPSTASH_REDIS_REST_TOKEN=your_redis_token

Optional Configuration

# Custom user ID for single-user setups
DEFAULT_USER_ID=my-fitness-journey

# Logging level for debugging
LOG_LEVEL=debug

# Custom port for development
PORT=3000

🤝 Contributing & Extending

Adding New MCP Tools

// Create new tool in tools/ directory
export const myCustomTool = {
  name: "my-custom-tool",
  description: "Description of what this tool does",
  inputSchema: {
    // Define parameters
  },
  handler: async (params) => {
    // Implementation
  }
}

// Register in tools/index.ts
export const tools = [
  // ... existing tools
  myCustomTool
]

Extending the Web Interface

• Add new components in components/ directory
• Create API routes in app/api/ for new functionality
• Update the main dashboard in app/page.tsx

Custom AI Integrations

• Implement additional MCP clients
• Add support for other AI platforms
• Create custom query processing logic

📄 License & Usage

MIT License - Feel free to use this project as a foundation for your own MCP servers and fitness applications.

This project demonstrates how to build production-ready MCP servers that bridge AI tools with domain-specific applications, providing a template for similar integrations in other domains.

---

🤖 Powered by Model Context Protocol
Bridging AI intelligence with real-world fitness data