Fit Happens Hackathon Project

Project Overview

This project is an evolution of our Apple Health MCP server that addresses two major problems with the original solution:

• the complex installation process (especially for non-technical users)
• synchronization of the latest data.

So we created:

• Backend that receives data (during the hackathon we used the Health Auto Export app)
• MCP server that communicates with the backend - can be connected to Claude or other LLM clients that support MCP
• N8N automation that sends data summaries at user-defined frequency

This is just the beginning of a larger ecosystem that will enable receiving personal health and fitness insights based on always up-to-date data!

Project Components

Backend (/backend)

FastAPI-based microservice that serves as the core data management system. It provides:

• REST API endpoints for workout and heart rate data with advanced filtering, sorting, and pagination
• Database models for storing workout sessions, heart rate data, and recovery metrics
• Data processing capabilities for health metrics and workout analytics
• Celery integration for background task processing
• Database migrations using Alembic for schema management

Key features:

• Comprehensive workout data storage (duration, distance, energy burned, environmental conditions)
• Heart rate monitoring and recovery analysis
• RESTful API with filtering and pagination
• PostgreSQL database with SQLAlchemy ORM
• Docker containerization support

MCP (/mcp)

Model Context Protocol (MCP) server that enables AI assistants to interact with fitness data. It provides:

• MCP tools for accessing workout and heart rate data through AI assistants
• HTTP transport for easy integration with AI agents
• Data validation using Pydantic schemas
• External API integration to fetch data from the backend service

Key features:

• get_workouts tool for retrieving workout data with filtering
• get_heart_rate tool for accessing heart rate and recovery metrics
• FastMCP framework for easy tool development
• Type-safe parameter validation
• Error handling and graceful fallbacks

N8N (/n8n)

Workflow automation system for generating automated fitness reports. It provides:

• Scheduled report generation (daily at 7 AM)
• Data processing workflows for fitness analytics
• Automated report delivery and notification systems
• Integration capabilities with external services

Key features:

• Automated daily fitness report generation
• Data aggregation and analysis workflows
• Report formatting and delivery automation
• Integration with the backend API for data retrieval

Architecture

The system follows a microservices architecture where:

• Backend serves as the data layer and API gateway
• MCP provides AI integration capabilities
• N8N handles automated workflows and reporting
• All components communicate via HTTP APIs

Getting Started

Each component has its own setup instructions in their respective directories:

• Backend: See /backend/README.md
• MCP: See /mcp/README.md
• N8N: Import the workflow from /n8n/report_automation.json

Technology Stack

• Backend: FastAPI, SQLAlchemy, PostgreSQL, Celery, Alembic
• MCP: FastMCP, Pydantic, httpx
• N8N: Workflow automation platform
• Infrastructure: Docker, Docker Compose