Workout Tracker MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Workout Tracker MCP Server Log a workout: Bench Press, 3 sets of 8 reps"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Workout Tracker MCP Server
A comprehensive Model Context Protocol (MCP) server for workout tracking with DynamoDB persistence and Exercise Database integration. Built with FastMCP.
Features
12 MCP Tools: Workout logging, volume calculation, DynamoDB operations, Exercise DB integration
2 MCP Prompts: AI-powered workout plan generation and formatting
1 MCP Resource: Exercise list
DynamoDB Integration: Persistent storage for workout plans with single-table design
Exercise Database: 1500+ exercises with search, filtering, and detailed information
Dual Transport: stdio (local) and HTTP/SSE (production) modes
Related MCP server: Workout Planner Ai MCP
Prerequisites
Before you begin, ensure you have:
Python 3.12+ (Python 3.14 recommended)
AWS Account with IAM credentials (Access Key ID and Secret Access Key)
AWS CDK (for infrastructure deployment) - Install with:
npm install -g aws-cdkTerminal/Command Line
Infrastructure Setup (One-Time)
⚠️ IMPORTANT: You must deploy the DynamoDB infrastructure to your AWS account before using this MCP server.
Option 1: Using AWS CDK (Recommended)
# Navigate to infrastructure directory
cd infrastructure
# Install CDK dependencies
npm install
# Bootstrap CDK in your AWS account (first time only)
cdk bootstrap
# Deploy the DynamoDB table
cdk deployThis will create:
DynamoDB table:
WorkoutPlansGlobal Secondary Indexes: GSI1 (Status), GSI2 (Exercise History)
Point-in-time recovery enabled
Billing mode: Pay-per-request
Option 2: Using the Bash Script
./scripts/create_dynamodb_table.shVerify Table Creation
aws dynamodb describe-table --table-name WorkoutPlans --region us-west-2Quick Start (2 Minutes)
1. Install & Setup
Run the automated setup script:
./setup.shDuring setup, you will be prompted to enter:
Your AWS Access Key ID
Your AWS Secret Access Key
AWS Region (default: us-west-2)
The script will:
✅ Install uv package manager (if needed)
✅ Detect Python 3.12+
✅ Create virtual environment
✅ Install all dependencies
✅ Prompt for AWS credentials and save them to ~/.bashrc or ~/.zshrc
✅ Verify DynamoDB access
Note: After setup, restart your terminal or run source ~/.bashrc (or ~/.zshrc) for AWS credentials to be available system-wide.
3. Start the Server
Local mode (stdio - for Claude Desktop, Claude Code):
uv run main.pyProduction mode (HTTP/SSE):
uv run main.py --httpServer will be available at http://localhost:8000/sse
Connect to MCP Clients
Option 1: Claude Desktop
Config file location:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Add to config:
{
"mcpServers": {
"workout-tracker": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/workout_tracker_mcp",
"main.py"
]
}
}
}Important:
Replace
/absolute/path/to/workout_tracker_mcpwith your actual pathAWS credentials are automatically configured by setup.sh
Restart Claude Desktop after saving
Option 2: Claude Code
The MCP server is already configured in .mcp.json. AWS credentials are automatically configured after running ./setup.sh.
Option 3: MCP Inspector (Testing)
npx @modelcontextprotocol/inspector uv run main.pyOpens interactive web UI at http://localhost:5173
Test Queries for MCP Clients
Once connected to Claude Desktop or Claude Code, try these queries:
1. Basic Workout Logging
Log a workout: Bench Press, 3 sets of 8 repsCalculate volume for: 185 lbs, 4 sets, 10 reps2. Exercise Database Search
Search for push exercisesFind all chest exercises using a barbellList exercises that target the quadricepsShow me all bodyweight exercises for legsWhat body parts can I train?3. Workout Plan Generation
Create a 12-week strength training program for an intermediate lifter who trains 4 days per weekGenerate a 6-week beginner workout plan focused on hypertrophy with 3 training days per week,
using only dumbbells, for a 28-year-old male4. DynamoDB Operations
Save a generated plan:
Save the workout plan you just generated for user_123Retrieve a saved plan:
Get the workout plan for user_123 with plan_id abc-123-defFormat for client:
Format this workout plan in a clean, printable format for my client5. Exercise Details
Get detailed information about exercise ID "VPPtusI"Show me exercise instructions for barbell squatsAvailable MCP Components
Tools (12)
Workout Tracking (2):
log_workout(exercise, sets, reps)- Log a workout sessioncalculate_volume(weight, sets, reps)- Calculate total volume
DynamoDB Operations (3):
save_workout_plan_to_dynamodb(workout_plan_json, user_id, ...)- Save workout planget_workout_plan_from_dynamodb(user_id, plan_id, ...)- Retrieve workout planlog_workout_session_to_dynamodb(workout_log_json, user_id, ...)- Log workout execution
Exercise Database (7):
get_all_exercises(limit, offset)- List all exercises (paginated)search_exercises(query, limit, offset, threshold)- Search exercises by nameget_exercise_by_id(exercise_id)- Get exercise detailsget_exercises_by_body_part(body_part, limit, offset)- Filter by body partget_exercises_by_target_muscle(target, limit, offset)- Filter by muscleget_exercises_by_equipment(equipment, limit, offset)- Filter by equipmentlist_body_parts()- List all body partslist_target_muscles()- List all target muscleslist_equipment()- List all equipment types
Prompts (2)
workout_plan_prompt()- Generate comprehensive workout plans with 10 parametersParameters: goal, experience_level, training_frequency, session_duration_min, equipment_available, age, gender, current_maxes, injuries_limitations, program_duration_weeks
Returns: Structured JSON for DynamoDB storage
format_workout_plan()- Transform DynamoDB JSON to client-friendly formatParameters: workout_plan_json
Returns: Beautiful markdown document
Resources (1)
workout://exercises/list- Static list of 8 basic exercises
Running Tests
End-to-End DynamoDB Test
uv run python tests/test_dynamodb_fetch.pyWhat it tests:
✅ Saves workout plan to DynamoDB
✅ Fetches plan from DynamoDB
✅ Verifies data integrity
✅ Cleans up test data
Expected output:
✅ SUCCESS - All verifications passed!
✓ Saved 27 entities to DynamoDB
✓ Fetched complete workout plan
✓ Verified 6 weeksExercise DB API Test
uv run python examples/test_api_slow.pyWhat it tests:
✅ Exercise listing
✅ Exercise search
✅ Exercise details
✅ Body part listing
Project Structure
workout_tracker_mcp/
├── main.py # MCP server (12 tools, 2 prompts, 1 resource)
├── setup.sh # Automated setup script
├── .mcp.json # MCP client configuration
├── ARCHITECTURE.md # System architecture documentation
│
├── src/ # Source modules
│ ├── db/
│ │ └── dynamodb_client.py # DynamoDB integration
│ └── client/
│ ├── mcp_client.py # MCP client wrapper
│ └── mcp_client_tools.py # MCP client helpers
│
├── src/prompts/ # Prompt templates
│ ├── workout_plan_prompt_template.py # Plan generation
│ └── format_workout_plan_prompt.py # Plan formatting
│
├── docs/ # Documentation
│ ├── DYNAMODB_DATA_MODEL.md # Schema reference
│ ├── DYNAMODB_INTEGRATION.md # Integration guide
│ ├── DYNAMODB_SETUP.md # Table setup
│ └── ...
│
├── infrastructure/ # Infrastructure as Code
│ └── dynamodb_stack.py # AWS CDK stack
│
├── scripts/ # Utility scripts
│ ├── create_dynamodb_table.sh # DynamoDB table creation
│ └── ...
│
├── tests/ # Test suite
│ ├── test_dynamodb_fetch.py # DynamoDB integration test
│ └── ...
│
└── examples/ # Usage examples
├── save_workout_plan_example.py # DynamoDB save
├── test_api_slow.py # Exercise DB test
└── mcp_client_usage.py # MCP client exampleConfiguration
Environment Variables
AWS Configuration:
Automatically configured by ./setup.sh (saved to ~/.bashrc or ~/.zshrc).
Server Configuration (optional):
export MCP_HOST="0.0.0.0" # Default: 0.0.0.0
export MCP_PORT="8000" # Default: 8000
export MCP_TRANSPORT="stdio" # Default: stdio (or "http")DynamoDB Table Setup
Option 1: Using the script (Quick)
./scripts/create_dynamodb_table.shOption 2: Using AWS CDK
cd infrastructure
cdk deployTable Details:
Name:
WorkoutPlansRegion:
us-west-2Billing: On-demand
Indexes: 2 GSIs (status, exercise history)
Deployment
Docker
# Build image
docker build -t workout-tracker-mcp .
# Run with environment variables
docker run -p 8000:8000 \
-e AWS_ACCESS_KEY_ID="your_key" \
-e AWS_SECRET_ACCESS_KEY="your_secret" \
-e AWS_DEFAULT_REGION="us-west-2" \
workout-tracker-mcpGoogle Cloud Run
# Deploy (will prompt for region)
gcloud run deploy workout-tracker \
--source . \
--platform managed \
--allow-unauthenticated \
--set-env-vars AWS_ACCESS_KEY_ID=your_key,AWS_SECRET_ACCESS_KEY=your_secretTroubleshooting
Server Won't Start
Check Python version:
python --version # Should be 3.12+Reinstall dependencies:
uv sync --reinstallAWS Credentials Issues
If AWS credentials are missing or not working:
Re-run setup:
./setup.shRestart terminal:
source ~/.bashrc # or ~/.zshrcVerify credentials:
aws sts get-caller-identity
Claude Desktop Can't Connect
Use absolute paths in config (not relative
~or./)Restart Claude Desktop after config changes
Check logs: Help > View Logs in Claude Desktop
Test server manually:
uv run main.pyshould start without errors
DynamoDB Table Not Found
# Check if table exists
aws dynamodb describe-table --table-name WorkoutPlans --region us-west-2
# Create table if missing
./scripts/create_dynamodb_table.shExample Workflows
Complete Workout Plan Creation
1. "Search for compound leg exercises"
2. "Create a 12-week strength program for intermediate lifter, 4 days/week"
3. "Save this plan for user_john_doe"
4. "Format the plan for my client to print"Exercise Discovery
1. "What body parts can I train?"
2. "Show me all chest exercises"
3. "Filter chest exercises that use dumbbells"
4. "Get detailed instructions for dumbbell bench press"Resources
License
MIT License
Support
Documentation: docs/
Architecture: ARCHITECTURE.md
Available Tools
14 toolscalculate_volumeA
Calculate total workout volume (weight x sets x reps)
Args:
weight: Weight used in pounds or kilograms
sets: Number of sets
reps: Number of repetitions per set
Returns:
Dictionary with volume calculation details
Inputs: reps (required), sets (required), weight (required).
get_all_exercisesA
Get a list of all exercises with pagination.
Args:
limit: Maximum number of exercises to return (default: 20, max: 100)
offset: Number of exercises to skip (default: 0)
Returns:
A formatted string containing exercise information including name, body parts,
target muscles, equipment, and instructions.
Inputs: limit, offset. Returns: result
get_exercise_by_idA
Get detailed information about a specific exercise by its ID.
Args:
exercise_id: The unique identifier of the exercise
Returns:
Detailed exercise information including name, body parts, target muscles,
equipment, instructions, and GIF URL.
Inputs: exercise_id (required). Returns: result
get_exercises_by_body_partA
Get exercises targeting a specific body part.
Args:
body_part: Body part to filter by (e.g., 'chest', 'back', 'legs', 'shoulders', 'arms')
limit: Maximum number of exercises to return (default: 20, max: 100)
offset: Number of exercises to skip (default: 0)
Returns:
List of exercises for the specified body part.
Inputs: body_part (required), limit, offset. Returns: result
get_exercises_by_equipmentA
Get exercises that use specific equipment.
Args:
equipment: Equipment to filter by (e.g., 'barbell', 'dumbbell', 'cable', 'body weight')
limit: Maximum number of exercises to return (default: 20, max: 100)
offset: Number of exercises to skip (default: 0)
Returns:
List of exercises using the specified equipment.
Inputs: equipment (required), limit, offset. Returns: result
get_exercises_by_target_muscleA
Get exercises targeting a specific muscle.
Args:
target: Target muscle to filter by (e.g., 'biceps', 'triceps', 'quads', 'hamstrings')
limit: Maximum number of exercises to return (default: 20, max: 100)
offset: Number of exercises to skip (default: 0)
Returns:
List of exercises targeting the specified muscle.
Inputs: target (required), limit, offset. Returns: result
get_workout_plan_from_dynamodbA
Retrieve a complete workout plan from DynamoDB
Fetches the entire workout plan structure including:
- Plan metadata (name, goal, duration, status, etc.)
- All weeks in the program
- All workout sessions for each week
- All exercises for each workout session
Args:
user_id: User ID who owns the plan
plan_id: Unique plan identifier
table_name: DynamoDB table name (default: WorkoutPlans)
region: AWS region (default: us-west-2)
Returns:
Dictionary containing the complete workout plan with plan_metadata and weeks,
or error information if the plan is not found or retrieval fails
Example:
result = get_workout_plan_from_dynamodb(
user_id="user_123",
plan_id="plan_abc123"
)
Inputs: plan_id (required), user_id (required), region, table_name.
list_body_partsB
Get a list of all available body parts in the database.
Returns:
Comma-separated list of body parts that can be used for filtering.
Inputs: no named parameters. Returns: result
list_equipmentA
Get a list of all available equipment types in the database.
Returns:
Comma-separated list of equipment types that can be used for filtering.
Inputs: no named parameters. Returns: result
list_target_musclesA
Get a list of all available target muscles in the database.
Returns:
Comma-separated list of target muscles that can be used for filtering.
Inputs: no named parameters. Returns: result
log_workoutB
Log a workout session
Args:
exercise: Name of the exercise performed
sets: Number of sets completed
reps: Number of repetitions per set
Returns:
Confirmation message with workout details
Inputs: reps (required), sets (required), exercise (required). Returns: result
log_workout_session_to_dynamodbA
Log a completed workout session to DynamoDB
Records the actual workout performed including session metadata and all exercise sets.
This creates:
- WorkoutLog (session metadata: start/end time, duration, energy level, etc.)
- ExerciseSetLog (one per set performed with weight, reps, RPE, form rating, etc.)
The workout_log_json should contain:
{
"plan_id": "plan_abc",
"week_number": 1,
"day_number": 1,
"workout_date": "2026-01-06",
"started_at": "2026-01-06T14:30:00Z",
"completed_at": "2026-01-06T15:45:00Z",
"duration_min": 75,
"perceived_difficulty": 8,
"energy_level": 7,
"sleep_quality": 8,
"pre_workout_nutrition": "protein shake + banana",
"bodyweight_lbs": 185,
"status": "completed",
"exercises": [
{
"exercise_id": "bench_press_barbell",
"exercise_name": "Barbell Bench Press",
"sets": [
{
"set_number": 1,
"set_type": "working",
"weight_lbs": 225,
"reps_completed": 5,
"reps_target": 5,
"rpe": 8,
"rir": 2,
"tempo_actual": "2-0-1-0",
"rest_seconds_actual": 180,
"form_rating": 9,
"notes": "Felt strong",
"failed": false,
"spotted": false
}
]
}
]
}
Args:
workout_log_json: JSON string of workout log data
user_id: User ID who performed the workout
log_id: Optional log ID (auto-generated UUID if not provided)
table_name: DynamoDB table name (default: WorkoutPlans)
region: AWS region (default: us-west-2)
Returns:
Dictionary with success status and statistics about logged entities
Example:
result = log_workout_session_to_dynamodb(
workout_log_json='{"plan_id": "plan_abc", "week_number": 1, ...}',
user_id="user_123"
)
Inputs: user_id (required), workout_log_json (required), log_id, region, +1 more.
save_workout_plan_to_dynamodbA
Save a workout plan to DynamoDB
Takes the JSON output from workout_plan_prompt and saves it to DynamoDB
following the schema defined in DYNAMODB_DATA_MODEL.md.
This creates all necessary entities:
- WorkoutPlan (plan metadata)
- WeekTemplate (one per week)
- WorkoutSession (one per workout day)
- PlannedExercise (one per exercise)
Args:
workout_plan_json: JSON string of workout plan (output from workout_plan_prompt)
user_id: User ID who owns this plan
plan_id: Optional plan ID (auto-generated UUID if not provided)
table_name: DynamoDB table name (default: WorkoutPlans)
region: AWS region (default: us-west-2)
Returns:
Dictionary with success status and statistics about created entities
Example:
result = save_workout_plan_to_dynamodb(
workout_plan_json='{"plan_metadata": {...}, "weeks": [...]}',
user_id="user_123"
)
Inputs: user_id (required), workout_plan_json (required), region, plan_id, +1 more.
search_exercisesA
Search for exercises by name or keyword with fuzzy matching.
Args:
query: Search query (exercise name or keyword)
limit: Maximum number of exercises to return (default: 20, max: 100)
offset: Number of exercises to skip (default: 0)
threshold: Fuzzy match threshold 0.0-1.0 (default: 0.3, lower = more results)
Returns:
List of exercises matching the search query with relevance scoring.
Inputs: query (required), limit, offset, threshold. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
log_workout and log_workout_session_to_dynamodb both log workouts but at different levels of detail and persistence, creating real ambiguity for an agent. The multiple get_exercises_by_* filters are largely distinct but could be confused with search_exercises, especially since they all return exercise lists.
Tool names consistently use snake_case with a verb_noun pattern, such as list_*, get_*, log_*, and save_*. Minor deviations like calculate_volume (no resource object) and the long 'to_dynamodb'/'from_dynamodb' suffixes are still readable and predictable.
With 14 tools, the count is on the higher end but still within a reasonable scope for an exercise database combined with workout plan and session logging. A few tools, especially the redundant log_workout, could be consolidated, but the overall count is not excessive.
The server provides save/get for workout plans and a session logger, but lacks list, update, and delete operations for plans or logs. There is also no way to retrieve a user's workout history, leaving significant lifecycle gaps that would cause agent failures in common tracking workflows.
Maintenance
Related MCP Connectors
Workout log your AI fills in: sets from text or notebook photos, daily plans, history and records.
Your strength-training data for any AI assistant: workouts, progress, muscle volume, routines.
Log workouts and meals by telling your AI. 873 exercises, muscle diagrams, food lookup.
Workout journal Claude and ChatGPT write to: log workouts, get a program, see your progress.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA comprehensive AI-powered fitness tracking application that enables AI tools to interact intelligently with user fitness data, providing personalized workout plans, nutrition tracking, and progress analysis through natural language.15MIT
- AlicenseNot gradedqualityCmaintenanceEnables creating workout plans, tracking progress, suggesting exercises, and calculating training volume through natural language, compliant with MCP protocol.MIT
- AlicenseNot gradedqualityBmaintenanceEnables conversational logging and retrieval of workouts, sets, weigh-ins, meals, goals, plans, and progress photos through MCP-capable AI clients, with authenticated per-user storage and export/query capabilities.ISC
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to plan, build, and log calisthenics workouts in a user's own account, including searching exercises, managing custom workouts and plans, reading progress and coaching data, and logging completed sessions. Account mutations require explicit confirmation, and workouts can be displayed as interactive cards in the chat.MIT