YAZIO MCP

English · Русский

A local Model Context Protocol server for working with your personal YAZIO nutrition diary from AI agents such as Claude Code, Claude Desktop, Codex, and Hermes Agent.

yazio-mcp speaks MCP over stdio and talks directly to YAZIO through a small, typed adapter maintained in this repository. It does not depend on the legacy yazio npm package or on a third-party proxy service.

[!WARNING] YAZIO does not publish or support a public developer API. This project uses a reverse-engineered, unofficial API that may change or be blocked without notice. Use it only with your own account and at your own risk. This project is not affiliated with, endorsed by, or sponsored by YAZIO GmbH.

What you can do

• Search the YAZIO product database using international English defaults (US, en_US) or configure any supported country and locale.
• Read breakfast, lunch, dinner, and snack entries for one day or a date range.
• Inspect daily calories, macros, water, weight, goals, and exercises.
• Add individual products or a compensated batch of meal items.
• Change the amount of an existing product entry, for example 200 g → 210 g.
• Remove an exact diary entry after explicit confirmation.
• Add water using a guarded read-modify-write flow.
• Compare periods and analyze nutrition trends by day, ISO week, or month.
• Flag days or meal slots that may be missing entries without inventing food.

Every tool returns:

• an outputSchema;
• machine-readable structuredContent;
• a short text fallback for older clients;
• normalized calories, protein, fat, carbohydrates, fiber, and sugar;
• a consistent error envelope with stable error codes.

Safety model

Nutrition writes are deliberately conservative:

• dry_run defaults to true;
• every write requires a client_request_id;
• duplicate detection runs before product writes;
• results are verified by reading the diary again;
• idempotency state survives process restarts;
• destructive actions use MCP multi-round-trip confirmation when supported;
• legacy clients receive a short-lived, one-time confirmation token;
• ambiguous writes are never retried blindly.

YAZIO does not expose a confirmed PATCH endpoint for consumed items. update_consumed_item therefore performs a guarded replacement:

1. Read and identify the exact original entry.
2. Add a replacement with a new UUID.
3. Verify that exact replacement UUID.
4. Delete the original UUID.
5. Verify the final state.
6. Remove the replacement as compensation if the original could not be deleted safely.

Updates of the same diary item are serialized across processes that share the same state file.

Available tools

Read tools

Tool	Description
get_user_profile	Privacy-filtered profile without email, birth date, tokens, or payment identifiers
get_goals	Calorie, macro, water, step, and weight goals
search_products	Text search with configurable country and locale
get_product	Product details and normalized nutrients per 100 g/ml
get_diary	Diary for one date or a range of up to 31 days
get_daily_summary	Daily nutrition, goals, water, steps, and four meal buckets
get_water_intake	Cumulative water intake for a date
get_weight	Latest known weight on or before a date
get_exercises	Training and custom training entries

Write tools

Tool	Description
add_consumed_item	Add one product with preview, duplicate detection, idempotency, and verification
add_meal_batch	Add up to 25 products and compensate earlier writes after a partial failure
update_consumed_item	Safely replace the amount of an existing product entry
remove_consumed_item	Remove an exact diary item after MRTR or one-time-token confirmation
add_water_intake	Add water by updating the cumulative daily total

Analytics tools

Tool	Description
get_nutrition_trends	Day/week/month averages, goals, variance, and stability
compare_periods	Compare calorie and macro averages for two periods
detect_probable_missing_meals	Report suspiciously empty meal slots; never writes food automatically

Requirements

• Node.js 20 or newer
• npm
• A personal YAZIO account that can sign in with email and password

Node.js 22 or 24 LTS is recommended for regular use.

Quick start

git clone https://github.com/tomastaker/yazio-mcp.git
cd yazio-mcp
npm ci
npm run build

The server entry point is:

node /absolute/path/to/yazio-mcp/dist/index.js

The process uses stdout exclusively for MCP JSON-RPC. Transport diagnostics are written to stderr.

Authentication and configuration

The server does not automatically load .env files. Pass credentials through your MCP client's environment configuration or a local secret manager.

Required for the first login:

Variable	Description
YAZIO_USERNAME	Email address of your personal YAZIO account
YAZIO_PASSWORD	Password of your personal YAZIO account

After login, the access and refresh tokens are cached locally. The password is never written to the token cache. A cached token is bound to a SHA-256 fingerprint of the normalized username, API base URL, and OAuth client ID, which prevents accidentally reusing a token from another account.

YAZIO does not offer public OAuth application registration. The adapter includes community-observed application-level OAuth credentials published by the MIT-licensed saganos/yazio_public_api project. They are shared application identifiers, not a user's personal secret. Both can be overridden together if YAZIO rotates them.

Optional variables

Variable	Default	Purpose
YAZIO_BASE_URL	https://yzapi.yazio.com/v19	Trusted local API configuration
YAZIO_TOKEN_CACHE_PATH	~/.yazio-mcp/token.json	Access/refresh token cache
YAZIO_MCP_STATE_PATH	~/.yazio-mcp/state.json	Idempotency and confirmation state
YAZIO_MCP_TIMEZONE	UTC	IANA timezone used for dates
YAZIO_PRODUCT_COUNTRIES	US	Comma-separated product countries
YAZIO_PRODUCT_LOCALES	en_US	Comma-separated product locales
YAZIO_DEFAULT_SEX	male	Search parameter required by the upstream API
YAZIO_HTTP_TIMEOUT_MS	15000	HTTP timeout, from 1,000 to 120,000 ms
YAZIO_CLIENT_ID	built in	Advanced paired OAuth override
YAZIO_CLIENT_SECRET	built in	Advanced paired OAuth override

Country, locale, and timezone are independent. For example, a German setup can use YAZIO_PRODUCT_COUNTRIES=DE, YAZIO_PRODUCT_LOCALES=de_DE, and YAZIO_MCP_TIMEZONE=Europe/Berlin. Multiple search values can be supplied as comma-separated lists; explicit countries and locales tool arguments override these defaults for an individual search.

NUTRITION_MCP_STATE_PATH and NUTRITION_MCP_TIMEZONE are accepted as deprecated migration aliases. Conflicting old and new values are rejected.

Client configuration

Replace /absolute/path/to/yazio-mcp in the examples below with the real checkout path. Prefer environment forwarding or an OS secret manager over storing credentials directly in a client configuration file.

Claude Code

Create .mcp.json in your project:

{
  "mcpServers": {
    "yazio": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/yazio-mcp/dist/index.js"],
      "env": {
        "YAZIO_USERNAME": "${YAZIO_USERNAME}",
        "YAZIO_PASSWORD": "${YAZIO_PASSWORD}"
      }
    }
  }
}

Verify the connection:

claude mcp list

Claude Desktop

Add the server to:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yazio": {
      "command": "node",
      "args": ["/absolute/path/to/yazio-mcp/dist/index.js"],
      "env": {
        "YAZIO_USERNAME": "set-locally",
        "YAZIO_PASSWORD": "set-locally"
      }
    }
  }
}

Claude Desktop stores literal environment values in its configuration. Protect that file with appropriate OS permissions.

Codex

Forward environment variables from ~/.codex/config.toml:

[mcp_servers.yazio]
command = "node"
args = ["/absolute/path/to/yazio-mcp/dist/index.js"]
env_vars = [
  "YAZIO_USERNAME",
  "YAZIO_PASSWORD"
]
default_tools_approval_mode = "writes"
startup_timeout_sec = 15
tool_timeout_sec = 90
enabled = true

Or register it with the CLI:

codex mcp add yazio \
  --env YAZIO_USERNAME="$YAZIO_USERNAME" \
  --env YAZIO_PASSWORD="$YAZIO_PASSWORD" \
  -- node /absolute/path/to/yazio-mcp/dist/index.js

Environment forwarding is safer than the CLI variant because literal --env values may be saved in local client configuration.

Hermes Agent

Add the server to ~/.hermes/config.yaml:

mcp_servers:
  yazio:
    command: "node"
    args: ["/absolute/path/to/yazio-mcp/dist/index.js"]
    env:
      YAZIO_USERNAME: "set-locally"
      YAZIO_PASSWORD: "set-locally"
      YAZIO_MCP_TIMEZONE: "UTC"
    timeout: 90
    connect_timeout: 15
    supports_parallel_tool_calls: false
    enabled: true

Parallel tool calls are disabled here as a conservative default for an unofficial API.

Example prompts

Search the YAZIO product database for Snickers and show me the best matches.

Show everything I logged for breakfast, lunch, dinner, and snacks today.

First show a dry-run, then add 80 g of product <product-uuid> to breakfast.

Change diary item <item-uuid> from 200 g to 210 g, but show me the preview first.

Compare my average calories and macros for the last two complete weeks.

Find days with probably missing breakfasts, but do not add anything.

An agent normally searches first, selects a product UUID, previews the write, and only then submits the mutation.

Responses and errors

Successful tools return both text and structured data:

{
  "ok": true,
  "data": {},
  "meta": {
    "timezone": "UTC",
    "backend": "yazio-unofficial",
    "generated_at": "2026-07-30T00:00:00.000Z"
  }
}

Failures set isError: true and use a machine-readable code:

{
  "ok": false,
  "error": {
    "code": "DUPLICATE_DETECTED",
    "message": "A probable duplicate entry was found; nothing was written.",
    "retryable": false
  }
}

For diary rows whose individual nutrition cannot be determined safely, get_diary exposes:

• totals_complete;
• totals_source (item_sum or daily_summary);
• missing_nutrition_item_ids.

This prevents a partial item sum from being presented as a complete total.

Recipes and unsupported operations

The adapter can read user recipe IDs and recipe details using community-observed endpoints. Recipe rows in the diary preserve recipe_id, and their names are enriched on a best-effort basis.

The following operations are intentionally not exposed as successful MCP tools because their upstream contracts are not sufficiently confirmed:

• adding a saved recipe portion to the diary;
• creating, updating, or deleting recipes;
• changing a recipe portion through update_consumed_item;
• native PATCH/PUT of consumed items;
• native date-range endpoints;
• full weight history;
• native barcode lookup;
• guaranteed transactional meal batches.

Recipe-row nutrients remain null when the upstream basis cannot be determined safely. Daily totals use the daily-summary endpoint instead.

Development

npm run lint
npm run typecheck
npm test
npm run build
npm run smoke

Run all default checks:

npm run check

The protocol smoke test starts a local mock YAZIO server, spawns the built MCP server over stdio, and validates:

• modern MCP 2026-07-28 negotiation;
• a real MRTR update/remove flow;
• legacy one-time-token confirmation;
• tool input/output schemas;
• structuredContent and privacy filtering.

Live tests

Live tests are opt-in:

export YAZIO_LIVE_TEST=1
export YAZIO_USERNAME='...'
export YAZIO_PASSWORD='...'
npm run test:live

The live write test creates a minimal product entry and removes that exact generated UUID in finally. If cleanup cannot be confirmed, the test fails. Avoid running live writes on an important diary date without checking the result in the YAZIO app.

Privacy and security

• The server is designed for one local user, not as a hosted multi-user API.
• User credentials are accepted only from environment variables.
• Passwords, authorization headers, tokens, and full profile responses are not written to logs or surfaced in tool errors.
• Token and state files use atomic writes and POSIX mode 0600; the default directory is created with 0700.
• Windows users must protect the cache directory with Windows ACLs because POSIX mode bits are not an ACL substitute.
• The profile tool uses an explicit allowlist and excludes email, birth date, payment identifiers, and upstream tokens.
• One-time confirmation tokens are stored only as SHA-256 digests.
• Write requests are not retried blindly after uncertain network failures.

See SECURITY_REVIEW.md for the current threat review.

API and MCP compatibility

The default /v19 API base was selected from observed behavior. Newer-looking URL versions are not necessarily released API versions; YAZIO can block or change any of them without warning.

The project uses the official split TypeScript SDK packages:

• @modelcontextprotocol/server@2;
• @modelcontextprotocol/client@2 for protocol tests.

The server opts into MCP 2026-07-28 through serveStdio and keeps the legacy stdio compatibility shim enabled for existing clients.

References:

• MCP specification 2026-07-28
• MCP 2026-07-28 changelog
• MCP TypeScript SDK migration guide
• fliptheweb/yazio-mcp
• juriadams/yazio

Implementation provenance and license notices are documented in THIRD_PARTY_NOTICES.md.

License

MIT