Skip to main content
Glama
Workout Tracker MCP Server

Workout Tracker MCP Server

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-cdk

  • Terminal/Command Line


Infrastructure Setup (One-Time)

⚠️ IMPORTANT: You must deploy the DynamoDB infrastructure to your AWS account before using this MCP server.

# 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 deploy

This will create:

  • DynamoDB table: WorkoutPlans

  • Global 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.sh

Verify Table Creation

aws dynamodb describe-table --table-name WorkoutPlans --region us-west-2

Quick Start (2 Minutes)

1. Install & Setup

Run the automated setup script:

./setup.sh

During 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.py

Production mode (HTTP/SSE):

uv run main.py --http

Server 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.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.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_mcp with your actual path

  • AWS 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.py

Opens 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 reps
Calculate volume for: 185 lbs, 4 sets, 10 reps
Search for push exercises
Find all chest exercises using a barbell
List exercises that target the quadriceps
Show me all bodyweight exercises for legs
What 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 week
Generate a 6-week beginner workout plan focused on hypertrophy with 3 training days per week,
using only dumbbells, for a 28-year-old male

4. DynamoDB Operations

Save a generated plan:

Save the workout plan you just generated for user_123

Retrieve a saved plan:

Get the workout plan for user_123 with plan_id abc-123-def

Format for client:

Format this workout plan in a clean, printable format for my client

5. Exercise Details

Get detailed information about exercise ID "VPPtusI"
Show me exercise instructions for barbell squats

Available MCP Components

Tools (12)

Workout Tracking (2):

  • log_workout(exercise, sets, reps) - Log a workout session

  • calculate_volume(weight, sets, reps) - Calculate total volume

DynamoDB Operations (3):

  • save_workout_plan_to_dynamodb(workout_plan_json, user_id, ...) - Save workout plan

  • get_workout_plan_from_dynamodb(user_id, plan_id, ...) - Retrieve workout plan

  • log_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 name

  • get_exercise_by_id(exercise_id) - Get exercise details

  • get_exercises_by_body_part(body_part, limit, offset) - Filter by body part

  • get_exercises_by_target_muscle(target, limit, offset) - Filter by muscle

  • get_exercises_by_equipment(equipment, limit, offset) - Filter by equipment

  • list_body_parts() - List all body parts

  • list_target_muscles() - List all target muscles

  • list_equipment() - List all equipment types

Prompts (2)

  • workout_plan_prompt() - Generate comprehensive workout plans with 10 parameters

    • Parameters: 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 format

    • Parameters: 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.py

What 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 weeks

Exercise DB API Test

uv run python examples/test_api_slow.py

What 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 example

Configuration

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.sh

Option 2: Using AWS CDK

cd infrastructure
cdk deploy

Table Details:

  • Name: WorkoutPlans

  • Region: us-west-2

  • Billing: 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-mcp

Google 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_secret

Troubleshooting

Server Won't Start

Check Python version:

python --version  # Should be 3.12+

Reinstall dependencies:

uv sync --reinstall

AWS Credentials Issues

If AWS credentials are missing or not working:

  1. Re-run setup:

    ./setup.sh
  2. Restart terminal:

    source ~/.bashrc  # or ~/.zshrc
  3. Verify credentials:

    aws sts get-caller-identity

Claude Desktop Can't Connect

  1. Use absolute paths in config (not relative ~ or ./)

  2. Restart Claude Desktop after config changes

  3. Check logs: Help > View Logs in Claude Desktop

  4. Test server manually: uv run main.py should 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.sh

Example 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

Available Tools

14 tools
calculate_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

    A3.5/5.0

    Scored across 14 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness2/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      15
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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