Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Bevel MCP How much protein have I had today compared with my goal?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for Bevel Health. Ask Claude, Grok Build or any MCP client about your Journal, meals, macro goals and workouts, and log new ones.
Unofficial. This project isn't affiliated with Bevel. It uses Bevel's private API, reverse-engineered from the iOS app, so it can break whenever Bevel changes it. Use it only with your own account.
You need a Mac with Node.js 20+, the Bevel app on your iPhone, and
mitmproxy (brew install mitmproxy) to get your first token.
git clone https://github.com/JoshPopov/Bevel-MCP.git && cd Bevel-MCPnpm ci && npm run setupSetup gets a token from your iPhone and shows what it will change. It asks before changing anything, then checks that the server answers and that Bevel accepts a real request. After that, try:
“What did I log in my Journal yesterday?”
“How much protein have I had today compared with my goal?”
“How has my leg press changed this month?”
“Log a banana as a snack at 3pm.” (needs writes)
Use with |
| What setup does |
Claude Code |
| Adds a user-scope |
Claude Desktop |
| Adds |
Grok Build |
| Runs |
Any MCP client |
| Shows and copies the JSON config |
Any AI agent |
| Copies a prompt telling the agent how to add the server |
Writes are off by default. Turn them on with npm run setup -- --writes and off with --read-only.
npm run doctor checks a Claude setup and prints a report you can share.
Related MCP server: google-health-mcp
Area | Read | Write |
Journal |
|
|
Meals |
|
|
Macro goals |
|
|
Workouts |
|
|
Account |
|
Every tool name starts with bevel_. † These requests come from the app's own traffic but haven't
been run against a real account yet.
Every write supports dryRun, reads fresh data first, and succeeds only when Bevel confirms the
record.
Not supported:
Logging completed workouts (they belong to Apple Health).
Sleep, Strain and Recovery scores (Bevel calculates them on the iPhone).
Cardio, custom foods and recipes.
Number and choice Journal factors.
Bevel signs you in with a token that lasts 60 days. Sign in with Apple can't be repeated from a
computer, so npm run token:capture takes the token from the Bevel app's own requests through a
local proxy. It checks the token with Bevel, then saves it to the macOS Keychain.
Capture installs a certificate on your iPhone that lets your Mac read Bevel's traffic. Remove it in Settings › General › VPN & Device Management when you're done.
The proxy intercepts only api.supersethealth.com, records nothing, and never prints the token.
npm run status shows how many days are left. To renew, run npm run token:capture again; your
Claude setup doesn't change.
Token details and the first-time iPhone steps
Your data travels only between your Mac, Bevel's API and the AI app you connect. There's no telemetry and no other server.
The token stays in your Keychain and is redacted from logs and errors.
Never share a token, an Authorization header or a raw capture. A doctor report is safe to share.
See SECURITY.md.
Guide: token, settings, connecting clients by hand, how writes behave, troubleshooting, reset
Development: tests, live checks against your account, mapping more of the API
API notes: every endpoint and payload seen so far
MIT. Bevel and Bevel Health belong to their owners. This project isn't affiliated with or endorsed by them.
Reports whether a Bevel API token is configured and decodes its non-secret JWT claims locally (account, issued/expiry times, lifetime). With checkApi, also makes one tiny request to confirm Bevel accepts it. Never returns the token.
Inputs: checkApi.
Clears a yes/no Journal factor for one day, so it shows as not answered — exactly what the app sends: the same entry with isNotSet: true and no boolValue. Does nothing if there is no entry or it is already cleared. Requires BEVEL_ENABLE_WRITES=true unless dryRun is set.
Inputs: factorKey (required), date, dryRun.
Creates a custom exercise (captured shape). Equipment, exercise type and muscle groups must be values Bevel is known to use (captured or already in your data) unless allowUnverifiedValues is set. Requires BEVEL_ENABLE_WRITES=true unless dryRun is set.
Inputs: name (required), equipment (required), defaultExerciseType (required), primaryMuscleGroups (required), +3 more.
Deletes a logged food the way the app does (soft delete: deletedAt is set on the same entry). Requires BEVEL_ENABLE_WRITES=true unless dryRun is set.
Inputs: id (required), date (required), dryRun.
Deletes a routine the way the app does (re-sent whole with isDeleted: true). Requires BEVEL_ENABLE_WRITES=true unless dryRun is set.
Inputs: id (required), dryRun.
Pulls custom Journal types via GET /api/journal/v1/custom-journal-types/pull, following pagination. Items are raw (schema not captured yet).
Inputs: maxPages, lastSyncDate.
Lists the foods logged on a day with time, servings and calories/protein/carbs/fat/fiber/sugar/caffeine, plus day totals.
Inputs: date, includeDeleted.
Pulls Journal data via GET /api/journal/v1/user-journal-data/pull, following pagination. Boolean entries are returned as {day, factorKey, value, ...}, optionally filtered by date and factor; value is null and cleared is true for a factor that was cleared in the app. Other collections (defaults) are returned raw because their schema has not been captured yet.
Inputs: date, limit, maxPages, factorKey, +1 more.
Lists calorie/protein/carb/fat goals (each with a start and optional end date) and marks the one active on the given day.
Inputs: date.
Lists strength routines (exercises, sets, weights) and custom exercises. Deleted items are hidden. Completed workouts are listed by bevel_get_workout_history; cardio and exercise notes are only counted.
Inputs: includeDeleted, includeSessions.
Lists completed strength workouts (most recent first): date, start time, duration, effort, and each exercise's sets with reps and weight in the unit you use, plus volume (reps × lb). Filter by date range or exercise name. Read-only.
Inputs: to, from, limit, exercise.
Logs a food (from bevel_search_food) to the Nutrition log, building the exact entry the app sends. Bevel files a log into breakfast/lunch/dinner by its time; there is no separate meal field. Requires BEVEL_ENABLE_WRITES=true unless dryRun is set.
Inputs: fdbId (required), date, time, query, +3 more.
Creates a routine, or (with id) replaces an existing routine's name and exercises — the app also re-sends routines whole. Each exercise is a built-in presetWorkoutId or a customExerciseId with sets of reps or durationSec. Supersets are not supported yet. Requires BEVEL_ENABLE_WRITES=true unless dryRun is set.
Inputs: name (required), exercises (required), id, dryRun, +2 more.
Searches foods the way the app does (generic + branded, 5 each). Returns fdbId, serving options and per-serving calories, protein, carbohydrate, fat, fiber, sugar and caffeine. Use an fdbId from here with bevel_log_food.
Inputs: query (required).
Sets a yes/no Journal factor (e.g. Added Sugar) for one day, the way the app does: if an entry for that factor and day exists it is updated in place (same uuid and createdAt), otherwise a new entry is created. Does nothing if the value is already set. Requires BEVEL_ENABLE_WRITES=true unless dryRun is set. Success means Bevel listed the entry's uuid as succeeded; confirm it in the app after restarting it.
Inputs: value (required), factorKey (required), date, dryRun, +1 more.
Sets daily calorie and macro goals from today on, exactly like the app: if the current goal started before today it is ended yesterday and a new goal starts today; if it already started today it is updated in place. Calories default to 4×protein + 4×carbs + 9×fat. Requires BEVEL_ENABLE_WRITES=true unless dryRun is set.
Inputs: fatG (required), carbsG (required), proteinG (required), dryRun, +1 more.
Changes the servings and/or time of a logged food (same entry, as the app does). Requires BEVEL_ENABLE_WRITES=true unless dryRun is set.
Inputs: id (required), date (required), time, dryRun, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 17 tools
Each tool targets a distinct resource+action (goals, journal factors, food logs, routines, workout history), and descriptions draw the key boundaries explicitly (e.g. get_workout_data = routines/exercises vs get_workout_history = completed workouts). Minor residual ambiguity: routine reads live inside bevel_get_workout_data while routine writes use bevel_save_routine/bevel_delete_routine, so an agent looking for 'get_routine' has to infer the mapping, and set vs clear journal boolean could be confused at a glance.
Nearly all 17 tools follow a consistent bevel_verb_noun snake_case pattern (get_, set_, clear_, delete_, create_, save_, search_, log_, update_). The only deviation is bevel_auth_status, a noun phrase without a verb, which breaks the pattern slightly but remains clear.
17 tools is on the high side but justified: the surface spans four distinct sub-domains (nutrition, workouts, journal, macro goals) plus auth. Each tool maps to a real operation rather than being redundant, though the nutrition set (5 tools) plus routine/journal writes pushes it toward the upper bound.
Food logs have full CRUD, and goals/journal booleans have read+write coverage, but there are notable gaps: workout history is read-only with no way to log a completed workout or cardio, routines can be created/replaced/deleted but not read via a dedicated tool, and custom journal types are read-only with raw schemas. Supersets and custom-journal-type creation are explicitly unsupported.
Read your workouts, history, and stats; create and schedule new workouts. Writes are additive only.
Read wearables and lab health data — sleep, activity, workouts, timeseries, lab tests and orders.
Read and write shared BitsWeave context, projects, tasks, and work sessions through MCP.
Hosted Apple Health MCP: workouts, sleep and HRV in ChatGPT, Claude, Gemini, Grok. Free, no export.
