mcp-server-fatsecret
This server lets you search FatSecret’s public food/recipe database and securely manage your own linked FatSecret account data via prepare→commit write operations.
Search available FatSecret tools/capabilities.
Link, check, complete, and disconnect your FatSecret OAuth1 account.
Search foods and recipes; fetch detailed nutrition, servings, ingredients, and directions.
Pick a serving from natural-language quantities before logging food.
Read your profile, food diary, weight history, and exercise diary.
Prepare/commit food diary entry creation, editing, deletion, and day copying.
Prepare/commit weight updates.
Prepare/commit exercise diary operations; log a one-off exercise via FatSecret’s template mechanism.
Read saved meals and prepare/commit saved-meal and saved-meal-item operations.
Prepare/commit favorite add/remove changes.
Commit prepared operations after review with an operation hash and idempotency key.
Use a gated fallback
profile.createpath only for dev/test.Call other allowlisted read-only FatSecret methods through a long-tail endpoint tool.
Writes require explicit enablement and follow a dry-run preview → commit workflow.
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., "@mcp-server-fatsecret Find me a healthy chicken recipe with under 500 calories"
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.
mcp-server-fatsecret
MCP server for the FatSecret Platform API — food/recipe search plus your own food diary, weight, exercise, saved meals, and favorites. Built for multiple named individuals sharing one hosted instance, each linking their own real FatSecret account.
This is an independent, unofficial project. It is not developed, endorsed or supported by FatSecret.
Scope
Public food/recipe database (search, nutrition detail, recipes) — read-only, no personal data involved, authenticated via OAuth2 client-credentials.
Your own FatSecret data — profile, food diary, weight diary, exercise diary, saved meals, favorites, custom foods — read AND write, authenticated via a per-person OAuth1 token you link yourself.
Every write goes through a prepare → commit ceremony:
fatsecret_prepare_*returns a dry-run preview with a hash; nothing is sent to FatSecret until afatsecret_commit_*call restates that hash plus a fresh idempotency key.
Related MCP server: fatsecret-mcp-server
Multi-user model
This server is designed to run as one shared instance behind a gateway
that authenticates callers (e.g. via your identity provider) and forwards the verified
caller identity as X-MCP-User. Each person's FatSecret OAuth1 token is
stored in its own encrypted row, keyed by that identity — nobody can reach
anyone else's diary, weight, or exercise data. If FATSECRET_TRUST_FORWARDED_USER
is unset (or the header is missing), every data/auth tool refuses outright.
Over stdio there is no gateway: set FATSECRET_DEV_USER to the identity the
per-user tools act as (required for the diary and auth tools). Tokens are then
stored in ~/.mcp-server-fatsecret/store.json unless FATSECRET_STORE_PATH
is set.
Setup
Register a developer app at platform.fatsecret.com to get a consumer key/secret. Premier tier is recommended if any user is outside the US — the free Basic tier's food database is US-only.
Set
FATSECRET_CONSUMER_KEY/FATSECRET_CONSUMER_SECRET.Generate an encryption key for the token store:
openssl rand -hex 32→FATSECRET_ENCRYPTION_KEY.Set
FATSECRET_ENABLE_WRITES=trueonce you're ready to allow writes (off by default).Each person links their own account once: call
fatsecret_start_auth, open the returned URL, sign into (or create) your fatsecret.com account, approve, then callfatsecret_complete_authwith the PIN FatSecret shows you.fatsecret_check_auth_status/fatsecret_disconnectmanage the link afterward.
Claude / Cursor config (local stdio)
{
"mcpServers": {
"fatsecret": {
"command": "npx",
"args": ["-y", "mcp-server-fatsecret"],
"env": {
"FATSECRET_CONSUMER_KEY": "...",
"FATSECRET_CONSUMER_SECRET": "...",
"FATSECRET_ENCRYPTION_KEY": "...",
"FATSECRET_DEV_USER": "you@example.com",
"FATSECRET_ENABLE_WRITES": "true"
}
}
}
}API tiers (Basic vs Premier) — read this before wondering why a food is missing
FatSecret's Platform API has a free Basic tier and a paid Premier tier, and the split materially affects what this server can do. Note the paid consumer app subscription is a different product and does not unlock any of this.
On Basic (the default):
The food database is US-only.
region=DKand other localization is a Premier feature, so non-US foods largely won't be found.Only
foods.searchv1 is available (v2–v5 are Premier).Custom foods (
food.create) are Premier-only — you cannot inject your own nutrition values.Listing favorites is Premier-only (
foods.get_favorites, most-eaten, recently-eaten). Adding and removing favorites still works.Everything that actually matters for a diary does work: logging, editing and deleting food entries, copying days, weight, saved meals, and exercise.
Set FATSECRET_PREMIER=true only if the app has genuinely been upgraded.
Tools backed by Premier-only methods are not registered at all on Basic, so
callers are never offered a tool that can only fail, and any direct call to one
fails fast with an explanation instead of an opaque upstream error.
Working with non-US foods on Basic: look the item up in a local food-data
source (e.g. Open Food Facts or a national food-composition database) to get its
real macros, then log the closest match from FatSecret's database with the
serving quantity scaled so the calories and macros line up. Search results
include per-serving macros in food_description to make that matching possible.
Write policy
FATSECRET_ENABLE_WRITES=true— required for any mutating call; off by default.FATSECRET_ENABLE_PROFILE_CREATE— separately gates the account-lessprofile.createfallback auth path (dev/test only; see below). Off by default even when general writes are enabled.FATSECRET_POLICY_PATH— optional JSON file to further restrict which capabilities/methods are allowed.FATSECRET_AUDIT_LOG— optional JSONL audit log path. Records tool/actingAs/status/a hash of the target — never the actual food, weight, or exercise data itself, since this is personal health-adjacent information.
Every write tool follows: fatsecret_prepare_* (dry-run, returns
operationHash) → fatsecret_commit_prepared_operation (requires the
operation object back, a restated confirmOperationHash, and a fresh
idempotencyKey). The operationHash is an HMAC-SHA256 signature keyed by
FATSECRET_PREPARE_SECRET (a random per-process key if unset — set it
explicitly when running several replicas or if prepared operations must
survive a restart). A prepared operation expires after 15 minutes, can only be
committed by the user who prepared it, and policy (FATSECRET_ENABLE_WRITES,
FATSECRET_POLICY_PATH, …) is re-evaluated at commit time; the
policyDecision in the preview is informational only. Idempotency keys are
scoped per user. The idempotency key is a local-only safety net —
FatSecret's API has no server-side idempotency support, unlike some other
providers — so retrying a commit with the same key only protects you within
this process's lifetime, not across a restart.
Auth model
The primary path is real 3-legged OAuth1 against your own fatsecret.com
account (fatsecret_start_auth / fatsecret_complete_auth), so your
FatSecret mobile app and this MCP server see the same diary.
A fallback path, profile.create, can mint an account-less token pair
(no real login, no companion-app access) for quick local testing — gated
separately behind FATSECRET_ENABLE_PROFILE_CREATE and its own commit tool,
fatsecret_commit_profile_create. Not recommended for real use.
Exercise logging — a real API limitation
FatSecret has no endpoint to log a single ad-hoc workout. It only supports a
recurring weekly template (exercise_entries.save_template) that gets
committed into a given day's diary (exercise_entries.commit_day), plus
shifting minutes between two exercises on an existing day
(exercise_entry.edit). fatsecret_log_one_off_exercise orchestrates the
template-swap-then-commit sequence for a one-off workout, but it is not
atomic across FatSecret's underlying calls — if it fails partway, your
template may be left modified; the tool reports which steps completed so you
can check and restore it.
Security / audit
See SECURITY.md. Credentials are read from the server environment only, never accepted as tool arguments. Per-user tokens are encrypted at rest (AES-256-GCM).
Optional HTTP server
npm run dev:http (or the published Docker image, which runs
dist/http.js) exposes /mcp over Streamable HTTP, gated by
MCP_HTTP_TOKEN. Intended to sit behind a reverse proxy that authenticates
callers and forwards their identity as X-MCP-User (only trusted when
FATSECRET_TRUST_FORWARDED_USER=true). The bearer token is compared in constant time, and the
server refuses to start if FATSECRET_TRUST_FORWARDED_USER=true but
MCP_HTTP_TOKEN is empty (MCP_HTTP_ALLOW_UNAUTHENTICATED does not override
this).
Variable | Default | Meaning |
|
| Bind address. |
|
| Listen port (1-65535). |
| - | Bearer token required on |
|
| Serve |
|
| Largest accepted request body; larger bodies get 413. |
| localhost origins | Comma-separated exact |
|
| Allow any |
| see below | Comma-separated host names accepted in the |
|
| Failed authentications per client address and window before further failures get 429; |
|
| Window for the limit above. |
|
| Upstream request timeout (1-600000 ms). |
The server refuses to start when it would expose /mcp without a token: a
non-loopback bind or MCP_ALLOW_ANY_ORIGIN=true without MCP_HTTP_TOKEN
(unless MCP_HTTP_ALLOW_UNAUTHENTICATED=true). Invalid numbers or booleans in
these variables also stop it at startup instead of being ignored. On a loopback
bind, only localhost, 127.0.0.1, [::1] or the bind address are accepted
in the Host header (DNS-rebinding protection); set MCP_ALLOWED_HOSTS to
change this. GET /healthz answers without authentication.
Security model
Each person links their own FatSecret account (OAuth1); diary, weight and exercise tools only use the token stored for the identity in
X-MCP-User. That header is only trusted withFATSECRET_TRUST_FORWARDED_USER=true, and only behindMCP_HTTP_TOKEN.Public food/recipe search uses one shared app credential (OAuth2 client credentials) for all callers.
User authentication and authorization belong in an identity-aware gateway in front of this server: it signs the user in, sets
X-MCP-Userand holds the bearer token. This server does not authenticate end users itself.Tool access is not data access: whoever can call
/mcpwith the bearer and a givenX-MCP-Uservalue acts as that user against FatSecret.Upstream requests never follow redirects, so signed requests and credentials are only sent to the configured API origin.
The HTTP server does not terminate TLS. Put it behind a TLS-terminating proxy or keep it on a private network.
Verification
npm run typecheck && npm test && npm run buildFor a live check against the real API (requires real credentials and a
linked account): npm run smoke:live.
API sources
License
Apache-2.0
Available Tools
28 toolsfatsecret_call_endpointCall FatSecret Method (long tail)ARead-onlyIdempotent
Allowlisted escape hatch for read-only (GET) FatSecret methods not covered by a dedicated tool. Mutating methods are rejected — use the prepare/commit tools instead.
Inputs: methodId (required), params.
fatsecret_check_auth_statusFatSecret Auth StatusARead-onlyIdempotent
Whether YOUR FatSecret account is linked.
Inputs: no named parameters.
fatsecret_commit_prepared_operationCommit Prepared Operation (FatSecret)A
Execute a previously prepared write after the caller has reviewed it. Requires the full operation object back plus a restated confirmOperationHash and a fresh idempotencyKey.
Inputs: operation (required), idempotencyKey (required), confirmOperationHash (required).
fatsecret_commit_profile_createCommit profile.create (fallback, dev/test only)ADestructive
Executes ONLY the profile.create fallback auth path. Requires FATSECRET_ENABLE_PROFILE_CREATE=true. Prefer fatsecret_start_auth/fatsecret_complete_auth for real accounts.
Inputs: operation (required), idempotencyKey (required), confirmOperationHash (required).
fatsecret_complete_authComplete FatSecret AuthA
Finish linking your FatSecret account using the PIN FatSecret displayed after fatsecret_start_auth.
Inputs: verifier (required).
fatsecret_disconnectDisconnect FatSecretADestructive
Remove your stored FatSecret tokens from this server.
Inputs: no named parameters.
fatsecret_get_exercise_entriesGet Exercise Diary (FatSecret)ARead-onlyIdempotent
Your exercise diary entries for one date, or a month summary with monthSummary=true. Also lists known exercise types when includeTypes=true.
Inputs: date, includeTypes, monthSummary.
fatsecret_get_foodGet Food (FatSecret)ARead-onlyIdempotent
Full nutrition detail + servings for one food by id (from fatsecret_search_foods).
Inputs: foodId (required).
fatsecret_get_food_entriesGet Food Diary (FatSecret)ARead-onlyIdempotent
Your food diary entries for one date, or a whole month with monthSummary=true.
Inputs: date, monthSummary.
fatsecret_get_profileGet Profile (FatSecret)CRead-onlyIdempotent
Your FatSecret profile status.
Inputs: no named parameters.
fatsecret_get_recipeGet Recipe (FatSecret)BRead-onlyIdempotent
Full ingredients/directions/nutrition for one recipe by id.
Inputs: recipeId (required).
fatsecret_get_saved_mealsGet Saved Meals (FatSecret)ARead-onlyIdempotent
Your saved-meal templates, or the foods inside one with savedMealId.
Inputs: savedMealId.
fatsecret_get_weight_historyGet Weight History (FatSecret)ARead-onlyIdempotent
Your weight history for a month containing the given date.
Inputs: date.
fatsecret_log_one_off_exerciseLog a One-Off Exercise (FatSecret)A
Orchestrates a one-off, never-to-repeat workout via FatSecret's template mechanism: saves your CURRENT template (to restore after), overwrites it with a template containing only this workout, commits that into the diary for the given date, then restores your original template. If a step fails partway, this tool attempts a best-effort restore and tells you to check fatsecret_get_exercise_entries / your template state — it cannot guarantee atomicity across FatSecret's three separate API calls. Requires FATSECRET_ENABLE_WRITES.
Inputs: minutes (required), exerciseId (required), idempotencyKey (required), date.
fatsecret_pick_servingPick a Serving (FatSecret)ARead-onlyIdempotent
Fuzzy-matches a natural-language quantity ("1 slice", "100g", "medium") against a food's servings, so you don't have to eyeball the raw servings array before logging it.
Inputs: foodId (required), quantityDescription.
fatsecret_prepare_exercise_operationPrepare: Exercise Diary Operation (FatSecret)A
Dry-run: prepare an exercise-diary write. FatSecret has no ad-hoc single-workout create — only a recurring weekly template (exercise_entries.save_template), committing that template into a day's diary (exercise_entries.commit_day), and shifting minutes between two exercises on an existing day (exercise_entry.edit). For a one-off workout you'll never repeat, use fatsecret_log_one_off_exercise instead.
Inputs: method (required), params (required), reason (required).
fatsecret_prepare_favorite_changePrepare: Favorite Change (FatSecret)A
Dry-run: mark/unmark a food or recipe as a favorite. (Adding/removing works on the Basic tier; listing favorites back requires Premier.)
Inputs: method (required), params (required), reason (required).
fatsecret_prepare_food_entries_copyPrepare: Copy Food Entries (FatSecret)A
Dry-run: prepare copying one day's food entries to another date.
Inputs: reason (required), toDate (required), fromDate (required), meal.
fatsecret_prepare_food_entry_createPrepare: Log Food Entry (FatSecret)A
Dry-run: prepare logging a food into your diary (use fatsecret_pick_serving first to get servingId). Nothing is written until fatsecret_commit_prepared_operation confirms this.
Inputs: meal (required), foodId (required), reason (required), servingId (required), +3 more.
fatsecret_prepare_food_entry_deletePrepare: Delete Food Entry (FatSecret)CDestructive
Dry-run: prepare deleting a food diary entry.
Inputs: reason (required), foodEntryId (required).
fatsecret_prepare_food_entry_editPrepare: Edit Food Entry (FatSecret)C
Dry-run: prepare editing an existing food diary entry.
Inputs: meal (required), reason (required), servingId (required), foodEntryId (required), +1 more.
fatsecret_prepare_saved_meal_item_operationPrepare: Saved Meal Item Operation (FatSecret)B
Dry-run: add/edit/remove a food inside a saved meal.
Inputs: method (required), params (required), reason (required).
fatsecret_prepare_saved_meal_operationPrepare: Saved Meal Operation (FatSecret)C
Dry-run: create/edit/delete a saved-meal template.
Inputs: method (required), params (required), reason (required).
fatsecret_prepare_weight_updatePrepare: Log Weight (FatSecret)B
Dry-run: prepare logging your current weight (kg). Height/goal-weight can only ever be set on your very first weigh-in — pass firstTimeSetup=true only then. Cannot backdate more than 2 days.
Inputs: reason (required), currentWeightKg (required), date, comment, +3 more.
fatsecret_search_capabilitiesSearch FatSecret CapabilitiesARead-onlyIdempotent
Find the right FatSecret tool/method. Use first if unsure what is available.
Inputs: limit, query.
fatsecret_search_foodsSearch Foods (FatSecret)ARead-onlyIdempotent
Search FatSecret's public food database by keyword. Each result's food_description carries per-serving calories and macros; use fatsecret_get_food for structured serving data. NOTE: on the free Basic tier this database is US-only — for Danish foods, look the item up in a Danish food-data source first, then log the closest match here with the serving quantity scaled so the macros line up.
Inputs: query (required), maxResults, pageNumber.
fatsecret_search_recipesSearch Recipes (FatSecret)ARead-onlyIdempotent
Search the public recipe database by keyword.
Inputs: query (required), maxResults, pageNumber.
fatsecret_start_authStart FatSecret AuthA
Start linking YOUR real fatsecret.com account. Returns an authorize URL — open it, log into (or create) your FatSecret account, and approve. FatSecret then shows you a PIN; pass it to fatsecret_complete_auth to finish.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Each tool targets a distinct resource or action, and descriptions are detailed, but the many prepare_* variants plus the commit tools and the escape hatch create mild potential for misselection, especially for new agents.
All tools use the fatsecret_ prefix with snake_case verb_noun names; the prepare/commit pattern is consistently applied, and verbs (search, get, pick, start, complete, commit) are clear and uniform.
28 tools is well above the 25-tool threshold, and while the domain is complex, the large number of near-parallel prepare_* operations makes the surface feel bloated.
The set covers auth, food/recipe search, diary entries (food, weight, exercise), saved meals, favorites, and profile, plus a read-only escape hatch. Minor gaps exist (e.g., no direct single-entry getter, no favorites list on Basic tier), but core workflows are covered.
Maintenance
Related MCP Connectors
Read your private Enshape diary and log meals through scoped account authorization.
Discover, preview, and save recipes and meal plans with RecipeBee; private actions require OAuth.
Log meals, check calories and macros, set up a nutrition plan, and search foods.
Food and nutrition data: search, macros, and comparisons
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for managing food diary, nutrition tracking, meal planning, and weight logging via the FatSecret Platform API.15MIT
- AlicenseNot gradedqualityDmaintenanceEnables searching and retrieving nutrition data, recipes, and managing food diary entries through the FatSecret API.MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to search foods and recipes, track diet, manage weight, and log exercise using the FatSecret Platform API.44136 npm11MIT
- AlicenseAqualityBmaintenanceEnables interaction with the FatSecret Platform API and member recipe/RDI workflows, including food data, diaries, and recipe operations through profile-based tool exposure.10MIT