Hevy MCP

Instructions

Implementation Reference

• src/tools/workouts.ts:81-102 (handler)

  Handler for the 'get-workout' tool: validates input, checks hevyClient availability, fetches workout by ID, formats it, and returns JSON or empty response if not found.

  server.tool(
  	"get-workout",
  	"Get complete details of a specific workout by ID. Returns all workout information including title, description, start/end times, and detailed exercise data.",
  	{
  		workoutId: z.string().min(1),
  	},
  	withErrorHandling(async ({ workoutId }) => {
  		if (!hevyClient) {
  			throw new Error(
  				"API client not initialized. Please provide HEVY_API_KEY.",
  			);
  		}
  		const data = await hevyClient.getWorkout(workoutId);
  
  		if (!data) {
  			return createEmptyResponse(`Workout with ID ${workoutId} not found`);
  		}
  
  		const workout = formatWorkout(data);
  		return createJsonResponse(workout);
  	}, "get-workout"),
  );

• src/tools/workouts.ts:84-86 (schema)

  Input schema for 'get-workout' tool: requires 'workoutId' as non-empty string.

  {
  	workoutId: z.string().min(1),
  },

• src/index.ts:40-40 (registration)

  Top-level call to register all workout tools, including 'get-workout'.

  registerWorkoutTools(server, hevyClient);

• src/utils/formatters.ts:117-147 (helper)

  Supporting helper function formatWorkout used in the handler to standardize workout data structure, including computed duration and flattened exercise/set details.

  export function formatWorkout(workout: Workout): FormattedWorkout {
  	return {
  		id: workout.id,
  		title: workout.title,
  		description: workout.description,
  		startTime: workout.start_time,
  		endTime: workout.end_time,
  		createdAt: workout.created_at,
  		updatedAt: workout.updated_at,
  		duration: calculateDuration(workout.start_time, workout.end_time),
  		exercises: workout.exercises?.map((exercise) => {
  			return {
  				index: exercise.index,
  				name: exercise.title,
  				exerciseTemplateId: exercise.exercise_template_id,
  				notes: exercise.notes,
  				supersetsId: exercise.supersets_id,
  				sets: exercise.sets?.map((set) => ({
  					index: set.index,
  					type: set.type,
  					weight: set.weight_kg,
  					reps: set.reps,
  					distance: set.distance_meters,
  					duration: set.duration_seconds,
  					rpe: set.rpe,
  					customMetric: set.custom_metric,
  				})),
  			};
  		}),
  	};
  }