HevyMCP - AI-Powered Fitness Assistant

🚀 HevyMCP - AI-Powered Fitness Assistant & MCP Server

HevyMCP is an AI-powered Model Context Protocol (MCP) server for the Hevy fitness app. It lets you log workouts, search exercises, manage routines, and more—using natural language, a web interface, or AI assistants like Claude and ChatGPT.

---

🌟 Features

• Natural language workout logging ("bench press 3x8 at 135 lbs")
• Smart exercise matching (fuzzy, NLP, user preferences)
• Routine & folder management
• Webhook subscriptions
• Modern web interface (demo & real mode)
• MCP server for AI assistants

---

⚡ Quick Start

🎮 Try in Playground (No Installation)

Experience HevyMCP instantly with our Smithery playground:

npx -y @smithery/cli install hevymcp --client claude

Or visit: Smithery MCP Registry and search for "hevymcp"

📦 Local Installation

1. Install dependencies

pip install -r requirements.txt

2. Set your Hevy API key (for real use)

# Create .env file
echo "HEVY_API_KEY=your_hevy_api_key_here" > .env

3. Run the web interface

python -m uvicorn app.main:app --reload --port 8000

• Visit: http://localhost:8000

For demo mode (no API key needed, sample data only):

export DEMO_MODE=true
python -m uvicorn app.main:app --reload --port 8000

---

🖥️ Web Interface

• Try workout logging, search, and muscle group browsing instantly.
• Demo mode: For public demo site only. No API key needed, safe for public use, sample data only.
• Real mode: For local install. Enter your API key for real logging (local only, never sent to third parties). Do NOT use demo mode locally.

---

🛠️ API Endpoints (for developers)

Routines

• GET /mcp/routines — List all routines
• POST /mcp/routines — Create a new routine
• GET /mcp/routines/{routine_id} — Get routine by ID
• PUT /mcp/routines/{routine_id} — Update a routine

Routine Folders

• GET /mcp/routine-folders — List all folders
• POST /mcp/routine-folders — Create a new folder
• GET /mcp/routine-folders/{folder_id} — Get folder by ID

Webhooks

• GET /mcp/webhooks — List all webhook subscriptions
• POST /mcp/webhooks — Create a webhook
• DELETE /mcp/webhooks/{webhook_id} — Delete a webhook

Other Endpoints

• POST /mcp/workout — Log a workout (NLP)
• GET /mcp/workouts — List recent workouts
• GET /mcp/exercises/search?query=bench — Search exercises
• GET /mcp/exercises/muscle-groups — List muscle groups

---

🤖 MCP Tools (for AI Assistants)

Workout Tools

• log_workout — Log workouts using natural language ("bench press 3x8 at 135 lbs")
• get_workout_history — List recent workouts with pagination
• get_workout_count — Get total workout statistics
• get_workout_events — Get workout update/delete events

Exercise Tools

• search_exercises — Search for exercises by name with fuzzy matching
• get_muscle_groups — List all available muscle groups
• get_exercises_by_muscle_group — Get exercises filtered by muscle group
• update_exercise_template — Modify existing exercise templates
• delete_exercise_template — Remove exercise templates

Routine Management

• list_routines — List all workout routines with pagination
• create_routine — Create new workout routines
• get_routine — Get specific routine by ID
• update_routine — Modify existing routines
• delete_routine — Remove routines

Folder Organization

• list_routine_folders — List all routine folders
• create_routine_folder — Create organization folders
• get_routine_folder — Get folder details by ID
• update_routine_folder — Modify folder properties
• delete_routine_folder — Remove folders

Webhook Integration

• list_webhooks — List all webhook subscriptions
• create_webhook — Create real-time event subscriptions
• delete_webhook — Remove webhook subscriptions

---

🧩 API Structure (for contributors)

• app/integrations/hevy_api.py — Hevy API client (add new endpoints here)
• app/endpoints/ — FastAPI endpoints (add new routes here)
• app/mcp_server.py — MCP tool definitions and handlers
• app/web_interface.py — Web UI logic (demo & real mode)

---

🛡️ Safety & Privacy

• Demo mode: No API key needed, no data saved, safe for public demos.
• Real mode: API key is only used locally, never sent to third parties.
• Never enter your real API key on a public/shared server!

---

🤝 Contributing

1. Fork this repo and clone it.
2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Add new endpoints/tools:
   • Add to hevy_api.py (API client)
   • Add to endpoints/ (FastAPI)
   • Add to mcp_server.py (MCP tools)
5. Open a pull request!

---

💬 Questions?

• Open an issue or discussion on GitHub.
• PRs and feedback welcome!