Hevy MCP

Instructions

Implementation Reference

• src/tools/templates.ts:70-86 (handler)

  Executes the tool logic: checks for hevyClient, fetches exercise template by ID, handles not found, formats with helper, returns JSON response.

  async ({ exerciseTemplateId }: { exerciseTemplateId: string }) => {
  	if (!hevyClient) {
  		throw new Error(
  			"API client not initialized. Please provide HEVY_API_KEY.",
  		);
  	}
  	const data = await hevyClient.getExerciseTemplate(exerciseTemplateId);
  
  	if (!data) {
  		return createEmptyResponse(
  			`Exercise template with ID ${exerciseTemplateId} not found`,
  		);
  	}
  
  	const template = formatExerciseTemplate(data);
  	return createJsonResponse(template);
  },

• src/tools/templates.ts:66-68 (schema)

  Zod schema for input parameters: exerciseTemplateId as non-empty string.

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

• src/tools/templates.ts:63-89 (registration)

  Registers the 'get-exercise-template' MCP tool with server.tool, specifying name, description, input schema, and error-handled handler function.

  server.tool(
  	"get-exercise-template",
  	"Get complete details of a specific exercise template by its ID, including name, category, equipment, muscle groups, and notes.",
  	{
  		exerciseTemplateId: z.string().min(1),
  	},
  	withErrorHandling(
  		async ({ exerciseTemplateId }: { exerciseTemplateId: string }) => {
  			if (!hevyClient) {
  				throw new Error(
  					"API client not initialized. Please provide HEVY_API_KEY.",
  				);
  			}
  			const data = await hevyClient.getExerciseTemplate(exerciseTemplateId);
  
  			if (!data) {
  				return createEmptyResponse(
  					`Exercise template with ID ${exerciseTemplateId} not found`,
  				);
  			}
  
  			const template = formatExerciseTemplate(data);
  			return createJsonResponse(template);
  		},
  		"get-exercise-template",
  	),
  );

• src/utils/formatters.ts:249-260 (helper)

  Formats raw ExerciseTemplate from API into simplified FormattedExerciseTemplate used in the tool response.

  export function formatExerciseTemplate(
  	template: ExerciseTemplate,
  ): FormattedExerciseTemplate {
  	return {
  		id: template.id,
  		title: template.title,
  		type: template.type,
  		primaryMuscleGroup: template.primary_muscle_group,
  		secondaryMuscleGroups: template.secondary_muscle_groups,
  		isCustom: template.is_custom,
  	};
  }