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. Not affiliated with or endorsed 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 a fatsecret_commit_* call restates that hash plus a fresh idempotency key.

Multi-user model

This server is designed to run as one shared instance behind a gateway that authenticates callers (e.g. via Entra ID) 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.

For local development without a gateway, set FATSECRET_DEV_USER to act as a single fixed identity over stdio.

Setup

1. 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.
2. Set FATSECRET_CONSUMER_KEY / FATSECRET_CONSUMER_SECRET.
3. Generate an encryption key for the token store: openssl rand -hex 32 → FATSECRET_ENCRYPTION_KEY.
4. Set FATSECRET_ENABLE_WRITES=true once you're ready to allow writes (off by default).
5. 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 call fatsecret_complete_auth with the PIN FatSecret shows you. fatsecret_check_auth_status / fatsecret_disconnect manage 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=DK and other localization is a Premier feature, so non-US foods largely won't be found.
• Only foods.search v1 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-less profile.create fallback 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 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).

Verification

npm run typecheck && npm test && npm run build

For a live check against the real API (requires real credentials and a linked account): npm run smoke:live.

API sources

• FatSecret Platform API docs
• Authentication guide

License

Apache-2.0