Fitness Coach MCP

🚀 Health & Fitness Coach MCP 💪

Health & Fitness Coach MCP is an all - around AI - powered fitness tracking application. It uses the Model Context Protocol (MCP) to combine traditional fitness apps with intelligent AI assistance, offering users a more personalized and efficient fitness experience.

🚀 Quick Start

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?"

✨ Features

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

📦 Installation

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

💻 Usage Examples

Basic Usage

// Log a workout
{
  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
  }
}

Advanced Usage

// Generate a personalized fitness plan
{
  tool: "generate-plan",
  parameters: {
    userId: "user123"
  }
}

📚 Documentation

🏗️ 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 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

🔧 Technical 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)

🔧 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

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