yazio-mcp-server

An MCP server over the YAZIO food diary. Ask a model what you have eaten today, log a meal, build a recipe from tracked products.

Hand-written, unlike the SDK it sits on: it exists to turn ~48 raw endpoints into a couple of dozen tools a model can use without a manual, which is judgement work a generator cannot do.

Built on yazio-sdk, which is generated from yazio-api-specification.

Running it

pip install yazio-mcp-server
yazio-mcp-server

Or from a checkout:

nix-shell --run "make run"

Or in a container:

docker compose up -d

The endpoint is http://127.0.0.1:8931/mcp, speaking streamable HTTP. The port avoids 8000 on purpose — that one collides with too much other tooling for a server whose URL is registered somewhere in advance.

Related MCP server: nutrition-mcp

In a container

The Dockerfile builds an Alpine image that runs the server as an unprivileged user (uid 10001) and holds nothing but the interpreter and the installed virtualenv — 60 MB on disk, 21 MB to pull. It binds 0.0.0.0, because a container's own loopback is reachable from nothing else.

One thing the image does that a plain pip install does not: it removes cryptography after installing. That package is 15 MB and arrives through mcp → pyjwt[crypto], for OAuth and JWT verification paths a Basic-auth server never takes — PyJWT falls back to its HMAC-only algorithm set, and TLS to YAZIO goes through the standard library's ssl either way. Adding an OAuth path to this server means dropping that line from the Dockerfile first.

Tagged releases are published to GHCR for amd64 and arm64, so there is usually nothing to build:

docker run --rm -p 127.0.0.1:8931:8931 ghcr.io/yazio-community/yazio-mcp-server:latest

v1.4.2 publishes 1.4.2, 1.4 and 1; latest follows final releases only, never a prerelease. From a checkout:

docker build -t yazio-mcp-server .
docker run --rm -p 127.0.0.1:8931:8931 yazio-mcp-server

The one thing worth knowing before deploying it: every hostname clients use to reach the server has to be named. The transport's DNS-rebinding guard accepts loopback and nothing more, so a compose service name, a Kubernetes Service or an Ingress host all come back as 421 Invalid Host header until they are added:

docker run --rm -p 8931:8931 yazio-mcp-server \
  yazio-mcp-server --host 0.0.0.0 --allowed-host yazio.example.com

docker-compose.yml does exactly this for the service name and publishes the port on loopback only — the credentials in play are a YAZIO password in reversible encoding, so anything wider belongs behind TLS.

On Kubernetes the same argument goes in args, and probes have to be TCP: the whole app sits behind Basic auth, so an unauthenticated HTTP probe reports 401 for a healthy server.

containers:
  - name: yazio-mcp
    image: yazio-mcp-server
    args: ["yazio-mcp-server", "--host", "0.0.0.0", "--allowed-host", "yazio-mcp.default.svc.cluster.local:*"]
    ports:
      - containerPort: 8931
    readinessProbe:
      tcpSocket:
        port: 8931
    securityContext:
      runAsNonRoot: true
      readOnlyRootFilesystem: true
      allowPrivilegeEscalation: false

Nothing is written to disk and no state survives a restart — tokens are cached in memory, per credential pair — so replicas need no coordination and can be scaled freely.

Using it from Claude Code

Registered at user scope, so it is available in every directory:

claude mcp add --transport http --scope user yazio http://127.0.0.1:8931/mcp \
  --header "Authorization: Basic $(printf '%s:%s' "$YAZIO_USERNAME" "$YAZIO_PASSWORD" | base64 -w0)"

The server has to be running for Claude Code to reach it; start it with the command above, and it will show as failed in claude mcp list when it is not.

Note that this writes the Basic credential into ~/.claude.json, where it sits in a form that is trivially reversible — it is your YAZIO password, not a token you can revoke on its own. claude mcp remove yazio --scope user takes it back out.

Authenticating

There is no separate account for this server: clients authenticate with the same username and password they use to log in to YAZIO, sent as HTTP Basic credentials — or, if the client cannot build those, as two plain headers. The server exchanges them for a YAZIO OAuth token on the first tool call and caches it per credential pair until it expires.

{
  "mcpServers": {
    "yazio": {
      "type": "http",
      "url": "http://127.0.0.1:8931/mcp",
      "headers": {
        // base64 of "username:password"
        "Authorization": "Basic bWVAZXhhbXBsZS5jb206aHVudGVyMg=="
      }
    }
  }
}

Basic auth is not what the MCP specification prescribes for HTTP transports — it expects OAuth — so clients have to be pointed at the server with an explicit header rather than through a discovery flow.

Without the base64 step

Some clients — LibreChat among them — let an administrator define custom headers but pass the values through verbatim, so there is no way to have the client assemble the base64 credential from a username and a password. For those, send the two values as separate headers instead:

{
  "mcpServers": {
    "yazio": {
      "type": "http",
      "url": "http://127.0.0.1:8931/mcp",
      "headers": {
        "X-Auth-Username": "me@example.com",
        "X-Auth-Password": "hunter2"
      }
    }
  }
}

The two forms are equivalent — the same login, the same token cache. When a request carries both, Authorization wins and the X-Auth-* headers are ignored. Sending only one half of the pair is refused with 400 Bad Request, rather than the 401 an unauthenticated request gets, so a client that is only missing a field can tell that apart from credentials YAZIO turned down. A blank value is not a credential either: once one of the headers is on the request, both have to carry something or the request is a 400.

Basic credentials are encoded, not encrypted. Bind to loopback, or terminate TLS in front of the server; never expose it over plain HTTP on a network you do not control.

Behind a reverse proxy, name the public hostname or the transport's DNS-rebinding guard will reject the request:

python3 -m yazio_mcp --host 0.0.0.0 --allowed-host yazio.example.com

Tools

Overview and nutrition

Products

Tracking

Recipes

Profile

get_profile returns the goal direction, activity level, units, height and birth date — context worth having before interpreting anyone's numbers.

Units

Energy is in kilocalories and macros are in grams. Vitamins and minerals are reported in milligrams: YAZIO stores them in grams too, but at that scale they are values like 0.00012 that round away to nothing. Every nutrient block carries a units map, so the mixture cannot be misread.

Micronutrients stay small even in milligrams, because product nutrients are per one base unit (see below) rather than per 100. Numbers that would round to zero at two decimals are reported to three significant digits instead, so a trace amount never reads as an absent one.

Product nutrients are stored per one base unit, not per 100: olive oil reads 8.84 kcal per gram. This is the factor create_recipe scales by, so it is worth knowing before touching that code.

How create_recipe works

YAZIO's recipe endpoint stores what the client submits and derives nothing: a recipe carries its own nutrient totals. So create_recipe resolves every ingredient to a real product, scales that product's nutrients to the amount the recipe uses, and sums them before posting. An ingredient that cannot be resolved fails the call rather than silently contributing zero.

Two of its rules come from the API rather than from taste, and both are enforced before the request goes out because the API signals them badly:

• At least two ingredients. One is rejected with "This collection should contain 2 elements or more".

• portion_count must be a whole number. Not merely integral in value — it has to serialise without a decimal point. 2 is accepted; 2.0 and 2.5 are both answered with a bare 500 and no message.

API behaviour this server works around

The full catalogue of undocumented API behaviour lives in the spec repo. These are the ones that shaped code here rather than the spec:

• The client version is checked, and it lives in the User-Agent. Anything unrecognised gets 403 {"error":"version_blocked"} on every endpoint except the token exchange. config.USER_AGENT carries the captured app's string and will need bumping when YAZIO retires that version — a sudden wall of 403s is the symptom, and it is the single most likely reason this server stops working one day.

• Product search requires sex and countries. search_products fills both from the user's profile rather than making a caller supply them.

• untrack_item cannot trust the delete endpoint. DELETE /v22/user/consumed-items takes a body of {"<bucket>": "<uuid>"} — a single string, not a list — and it also accepts an ?id= query parameter, answers 204, and does nothing. So the tool looks the entry up first to learn its bucket, and reads the day back afterwards rather than believing the status code.

• create_recipe validates before sending. Two API rules are enforced client-side because the API signals them badly: fewer than two ingredients is rejected with a message about collections, and a portion_count that serialises with a decimal point (2.0, 2.5) is answered with a bare 500 and no message at all.

Development

nix-shell            # builds yazio_sdk from its PyPI release
make test            # mocked suite, never touches a real account
make lint

yazio_sdk comes from PyPI everywhere — the dev shell, CI and released builds alike. The dev shell pins one version of it (see shell.nix); keep that inside the range pyproject.toml declares when either moves.

The suite mocks every HTTP call, so it covers the shaping logic but cannot catch the API contradicting the spec. If a shape looks wrong rather than the server's handling of it, the problem is upstream — reproduce it against the spec repo and fix it there.

Licence

MIT.