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

---

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.

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

2. Exercise Database Search

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

• MCP Specification
• FastMCP Documentation
• Claude Desktop MCP Guide
• Exercise DB API
• Architecture Documentation

---

License

MIT License

Support

• Documentation: docs/
• Architecture: ARCHITECTURE.md