exercisedb

An MCP server and CLI over the YMove exercise API, which catalogues more than 1,400 exercises with video. Six tools cover the everyday questions a training app or an agent asks of that catalogue: find exercises that fit a filter, open one exercise in full, have a workout generated for a set of muscle groups, have a whole multi-week program generated, and read the two vocabularies (muscle groups and exercise types) the filters draw from, each with its exercise counts.

Whatever the API answers comes back exactly as it answered: each tool returns a single text item carrying the upstream JSON, unchanged. Nothing is reshaped, cached or stored, which also means the API's own properties carry through — exercise video URLs, for instance, are signed by the upstream service and expire after 48 hours.

The six tools:

• search_exercises — filter the catalogue by free text, muscle group, exercise type, equipment and difficulty, keep only exercises that have video, and page through the results. Every argument is optional.
• get_exercise — one exercise by its ID or slug: video URLs, instructions and the muscles it works.
• generate_workout — a structured workout with sets, reps and rest times. muscleGroup is required; it takes an array of muscle groups, and a single string is accepted and treated as a one-element array. Equipment, exercise types, difficulty, exercise count, structure, rounds and warmup / cooldown blocks are all tunable.
• generate_program — a multi-week training program with periodization, shaped by goal, difficulty, days per week, number of weeks and available equipment.
• list_muscle_groups — every muscle group in the catalogue, with its exercise count.
• list_exercise_types — every exercise type, with counts.

Arguments that the REST API documents but the tool set does not expose are deliberately left out: the search tool has no white-background / gym-video or video-tag filters and no include / exclude video-list switches.

Configuration

The API is keyed. Set your YMove key before running:

export YMOVE_API_KEY="..."

Every request carries the key as the X-API-Key header. A call made without the key fails with YMOVE_API_KEY is not set before any request leaves the process. Validation also runs before any request: a missing required argument reports <tool>: missing required argument: <name> and a wrong-typed one reports <tool>: argument <name> has the wrong type. An upstream failure is reported as upstream error: HTTP <status> from ymove-api, or upstream unreachable: ymove-api when the API cannot be reached at all.

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/exercisedb search_exercises '{"muscleGroup":"chest","hasVideo":true}'
npx @reneturcios/exercisedb get_exercise '{"id":"barbell-squat"}'
npx @reneturcios/exercisedb generate_workout '{"muscleGroup":["chest","triceps"],"exerciseCount":8}'
npx @reneturcios/exercisedb generate_program '{"goal":"strength","weeks":6,"daysPerWeek":3}'
npx @reneturcios/exercisedb list_muscle_groups '{}'
npx @reneturcios/exercisedb --version

Output is the upstream JSON body, unchanged. Exit codes: 0 on success, 1 on a runtime error (including a validation, API-key or upstream failure), 2 on a usage error.

MCP server

npx -y @reneturcios/exercisedb mcp

MCP client config:

{
  "mcpServers": {
    "exercisedb": {
      "command": "npx",
      "args": ["-y", "@reneturcios/exercisedb", "mcp"],
      "env": { "YMOVE_API_KEY": "..." }
    }
  }
}

Docker

docker run -i -e YMOVE_API_KEY="..." ghcr.io/cloudcorprecords/exercisedb
docker run --rm -e YMOVE_API_KEY="..." ghcr.io/cloudcorprecords/exercisedb list_exercise_types '{}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

Lice

... View full README on GitHub