Health & Fitness Coach MCP

# Health & Fitness Coach MCP 💪 [](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fyour-username%2Fhealth-fitness-coach-mcp&env=OPENAI_API_KEY) <a href="https://cursor.com/install-mcp?name=health-fitness-coach&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAvc3NlIn0="><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add Health & Fitness Coach MCP server to Cursor" height="32" /></a> ## 🎯 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 ```typescript // 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 ```typescript // 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 ```typescript // 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 ```typescript // 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 ```typescript // 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 ```typescript // 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 ```typescript // 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** ```bash 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** ```json { "mcpServers": { "health-fitness-coach": { "url": "http://localhost:3000/sse" } } } ``` #### **Claude Desktop Configuration** ```json { "mcpServers": { "health-fitness-coach": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"] } } } ``` ### **3. Test the Integration** ```bash # 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** ```typescript // 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** ```typescript // 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** ```typescript // 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** ```bash # 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** ```javascript // 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** ```env # 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** ```env # 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** ```typescript // 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*