> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chrisdoc.dev/hevy-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# Body measurement tools — log and track Hevy body stats

> Reference for the 4 Hevy MCP body measurement tools: get-body-measurements, get-body-measurement, create-body-measurement, and update-body-measurement.

Hevy MCP provides **4 tools** for reading and writing dated body measurements. Each entry is keyed to a calendar date and can store weight, lean mass, body fat percentage, and a full set of circumference measurements. The tools cover the complete lifecycle: browse history, look up a specific date, log a new entry, and correct an existing one.

## get-body-measurements

Lists dated body measurements for the account, returned from newest to oldest. Use this tool to browse measurement history or retrieve multiple entries in one call.

**Kind:** Read-only

<ParamField query="page" type="integer" default="1">
  Page number to retrieve, starting at `1`.
</ParamField>

<ParamField query="pageSize" type="integer" default="10">
  Number of measurements to return per page. Maximum is `10`.
</ParamField>

<Note>
  Results are paginated. `page` starts at `1` and `pageSize` is capped at `10`. Iterate with incrementing `page` values to walk through the full history.
</Note>

***

## get-body-measurement

Retrieves the body measurement entry for a single specific date. Use this tool when the exact measurement date is already known. For browsing or discovering dates, use `get-body-measurements` instead.

**Kind:** Read-only

<ParamField query="date" type="string" required>
  The date of the body measurement to retrieve, in `YYYY-MM-DD` format. Example: `2024-03-15`.
</ParamField>

<Note>
  At most one measurement entry exists per date. If no entry exists for the supplied date, the tool returns a `null` body measurement rather than an error.
</Note>

***

## create-body-measurement

Creates a new dated body measurement on the Hevy account. Supply the date and at least one numeric measurement field. Use this tool only for dates that do not yet have an entry; to modify an existing entry use `update-body-measurement`.

**Kind:** Write (mutation)

<ParamField body="date" type="string" required>
  The date for the new measurement, in `YYYY-MM-DD` format. Must be unique — no measurement entry may already exist for this date.
</ParamField>

<ParamField body="weightKg" type="float">
  Body weight in kilograms.
</ParamField>

<ParamField body="leanMassKg" type="float">
  Lean body mass in kilograms.
</ParamField>

<ParamField body="fatPercent" type="float">
  Body fat percentage.
</ParamField>

<ParamField body="neckCm" type="float">
  Neck circumference in centimeters.
</ParamField>

<ParamField body="shoulderCm" type="float">
  Shoulder circumference in centimeters.
</ParamField>

<ParamField body="chestCm" type="float">
  Chest circumference in centimeters.
</ParamField>

<ParamField body="leftBicepCm" type="float">
  Left bicep circumference in centimeters.
</ParamField>

<ParamField body="rightBicepCm" type="float">
  Right bicep circumference in centimeters.
</ParamField>

<ParamField body="leftForearmCm" type="float">
  Left forearm circumference in centimeters.
</ParamField>

<ParamField body="rightForearmCm" type="float">
  Right forearm circumference in centimeters.
</ParamField>

<ParamField body="abdomen" type="float">
  Abdomen circumference in centimeters.
</ParamField>

<ParamField body="waist" type="float">
  Waist circumference in centimeters.
</ParamField>

<ParamField body="hips" type="float">
  Hips circumference in centimeters.
</ParamField>

<ParamField body="leftThigh" type="float">
  Left thigh circumference in centimeters.
</ParamField>

<ParamField body="rightThigh" type="float">
  Right thigh circumference in centimeters.
</ParamField>

<ParamField body="leftCalf" type="float">
  Left calf circumference in centimeters.
</ParamField>

<ParamField body="rightCalf" type="float">
  Right calf circumference in centimeters.
</ParamField>

<Warning>
  If an entry already exists for the supplied `date`, the Hevy API returns **409 Conflict**. Use `update-body-measurement` to modify an existing entry instead.
</Warning>

<Note>
  Fields set to `null` or omitted are not sent to the API and cannot be used to clear previously stored values. To change an existing value, use `update-body-measurement` with the new numeric value.
</Note>

***

## update-body-measurement

Updates the body measurement for a date that already has an existing entry. Supply `date` and at least one numeric field to change. To create an entry for a date that has no record yet, use `create-body-measurement`.

**Kind:** Write (mutation)

<ParamField body="date" type="string" required>
  The date of the measurement to update, in `YYYY-MM-DD` format. An entry must already exist for this date.
</ParamField>

<ParamField body="weightKg" type="float">
  Body weight in kilograms.
</ParamField>

<ParamField body="leanMassKg" type="float">
  Lean body mass in kilograms.
</ParamField>

<ParamField body="fatPercent" type="float">
  Body fat percentage.
</ParamField>

<ParamField body="neckCm" type="float">
  Neck circumference in centimeters.
</ParamField>

<ParamField body="shoulderCm" type="float">
  Shoulder circumference in centimeters.
</ParamField>

<ParamField body="chestCm" type="float">
  Chest circumference in centimeters.
</ParamField>

<ParamField body="leftBicepCm" type="float">
  Left bicep circumference in centimeters.
</ParamField>

<ParamField body="rightBicepCm" type="float">
  Right bicep circumference in centimeters.
</ParamField>

<ParamField body="leftForearmCm" type="float">
  Left forearm circumference in centimeters.
</ParamField>

<ParamField body="rightForearmCm" type="float">
  Right forearm circumference in centimeters.
</ParamField>

<ParamField body="abdomen" type="float">
  Abdomen circumference in centimeters.
</ParamField>

<ParamField body="waist" type="float">
  Waist circumference in centimeters.
</ParamField>

<ParamField body="hips" type="float">
  Hips circumference in centimeters.
</ParamField>

<ParamField body="leftThigh" type="float">
  Left thigh circumference in centimeters.
</ParamField>

<ParamField body="rightThigh" type="float">
  Right thigh circumference in centimeters.
</ParamField>

<ParamField body="leftCalf" type="float">
  Left calf circumference in centimeters.
</ParamField>

<ParamField body="rightCalf" type="float">
  Right calf circumference in centimeters.
</ParamField>

<Warning>
  If no entry exists for the supplied `date`, the Hevy API returns **404 Not Found**. Use `create-body-measurement` to create a new entry for that date first.
</Warning>

<Note>
  You must provide at least one numeric measurement field; calling this tool with only `date` and no measurement fields is rejected. Fields set to `null` are omitted and cannot clear previously stored values — only supplying a new numeric value overwrites an existing one.
</Note>

***

## Date format

All body measurement tools use **calendar dates** in `YYYY-MM-DD` format — for example, `2024-03-15`. There is no time component. The Hevy API enforces a strict one-entry-per-date constraint, so the date acts as the unique key for every measurement record.

```text theme={null}
Valid:   2024-03-15
Valid:   2023-12-01
Invalid: 2024-3-15     (month not zero-padded)
Invalid: 15-03-2024    (wrong order)
Invalid: 2024-03-15T08:00:00Z  (timestamp not accepted)
```

***

## Measurement fields

All numeric fields are optional on both `create-body-measurement` and `update-body-measurement`. You may record any combination that is relevant to a given weigh-in.

| Field            | Unit | Description                 |
| ---------------- | ---- | --------------------------- |
| `weightKg`       | kg   | Total body weight           |
| `leanMassKg`     | kg   | Lean body mass              |
| `fatPercent`     | %    | Body fat percentage         |
| `neckCm`         | cm   | Neck circumference          |
| `shoulderCm`     | cm   | Shoulder circumference      |
| `chestCm`        | cm   | Chest circumference         |
| `leftBicepCm`    | cm   | Left bicep circumference    |
| `rightBicepCm`   | cm   | Right bicep circumference   |
| `leftForearmCm`  | cm   | Left forearm circumference  |
| `rightForearmCm` | cm   | Right forearm circumference |
| `abdomen`        | cm   | Abdomen circumference       |
| `waist`          | cm   | Waist circumference         |
| `hips`           | cm   | Hips circumference          |
| `leftThigh`      | cm   | Left thigh circumference    |
| `rightThigh`     | cm   | Right thigh circumference   |
| `leftCalf`       | cm   | Left calf circumference     |
| `rightCalf`      | cm   | Right calf circumference    |