Fitatu

fitatu-api

An unofficial Python client for the API of Fitatu, the calorie counter, built to be driven by AI agents and scripts. It reads and writes the food diary, activities, body measurements and water, reads and sets goals, and reads summaries and the food catalog. FitatuTools turns the diary into tools a language model can call. The session handling follows python-garminconnect: log in once, keep one session file, let the client refresh it.

Unofficial. This project is not affiliated with or endorsed by Fitatu Sp. z o.o. The API

was reverse-engineered from the Fitatu apps and can change without notice. Automated access

may break Fitatu's Terms of Service; check them, and use the library only with your own

account and at your own risk. The MIT licence covers this code, not the Fitatu service, its

API or its data.

Install

Python 3.11 or newer; the only dependency is requests (and tzdata on Windows).

pip install fitatu-api                                     # the library and the fitatu-api command

pip install "fitatu-api[mcp]" # plus fitatu-mcp, the MCP server pip install "git+https://github.com/Jezue/fitatu_library" # unreleased changes from main

To work on the library or run its tests offline, clone it instead: git clone https://github.com/Jezue/fitatu_library && cd fitatu_library && pip install -e ".[dev]".

Quick start

fitatu-api login   # asks for e-mail and password, writes ~/.fitatu/session.json

Signed up with Apple or Facebook? Then the account has no password: copy the session from the web app with fitatu-api import-session instead, as described under Authentication & session file.

from datetime import date

from fitatu_api import FitatuApiClient

with FitatuApiClient.from_session() as client: # closes the HTTP connections at the end user_id = client.auth.fitatu_user_id today = date.today()

day = client.planner.get_day(user_id, today) for meal_key, meal in day["dietPlan"].items(): for row in meal["items"]: print(meal_key, row["name"], row["energy"], row["planDayDietItemId"])

egg = client.search_food("jajko kurze", limit=1)[0] # search rows carry the id as foodId added = client.planner.add_product_to_day_meal( user_id, today, meal_type="breakfast", product_id=egg["foodId"], measure_id=egg"measure", measure_quantity=2, # 2 of the hit's measure ) print("added row", added["row_id"])

How writes, row ids and removals work: docs/PLANNER.md.

To copy a catering diet's menu into the diary (safe to run again), use catering_sync.py from the repository: Importing a catering menu.

For AI agents

FitatuTools exposes 47 tools (read the day, search food, log food, weight, water, workouts, private recipes and products, ...) with JSON Schema inputs and read-only / destructive / idempotent annotations. call() never raises: it returns {"ok": true, "data": ...} or {"ok": false, "error": {"error_type", "message", "retryable", "hint", ...}}, so the model can read what went wrong. SYSTEM_PROMPT is the recommended system prompt: the rules the model needs on top of the tool descriptions (read before writing, users' own meal names, data.ok, confirmations). The model asks get_today for the date, in the account's time zone.

import json

import anthropic

from fitatu_api import FitatuTools from fitatu_api.agent import READ_ONLY_TOOLS, SYSTEM_PROMPT, anthropic_tools # openai_tools() for OpenAI

client = anthropic.Anthropic() messages = [{"role": "user", "content": "How many kcal did I eat today?"}]

Only the read tools, as this loop runs tool calls without asking the user: call() refuses

any other tool, which the model can still name.

with FitatuTools.from_session(tools=READ_ONLY_TOOLS) as tools: while True: response = client.messages.create( model="claude-opus-5-5", max_tokens=16000, system=SYSTEM_PROMPT, tools=anthropic_tools(READ_ONLY_TOOLS), messages=messages, ) messages.append({"role": "assistant", "content": response.content}) if response.stop_reason != "tool_use": break results = [ { "type": "tool_result", "tool_use_id": block.id, "content": json.dumps(tools.call(block.name, block.input)), } for block in response.content if block.type == "tool_use" ] messages.append({"role": "user", "content": results}) if response.stop_reason != "end_turn": # max_tokens or refusal: the answer is cut or missing raise RuntimeError(f"the model stopped early: {response.stop_reason}") print("".join(block.text for block in response.content if block.type == "text"))

The write tools (log food, update, move, copy and delete rows, weight, water, workouts, private recipes and products) need a loop that asks the user before destructive calls; it is in docs/AGENTS.md, with the tool table, the calls never to expose (session tokens, catalog writes), how to make writes safe to repeat, what to do per error_type, the OpenAI variant, long-running hosts, and how to try the tools without an account against the offline test backend.

MCP

fitatu-mcp serves the same tools to Claude Code, Claude Desktop and other MCP hosts over stdio, with SYSTEM_PROMPT as its instructions and three Polish slash commands (podsumowanie_dnia, przeglad_tygodnia, zaloguj_posilek):

pipx install "fitatu-api[mcp]"

fitatu-api login claude mcp add fitatu --scope user -- fitatu-mcp # fitatu-mcp --read-only: the read tools only

fitatu-mcp --http serves the same tools over HTTP, with a token, for n8n, another computer or Docker (the repository has a Dockerfile): docs/AGENTS.md.

Without an account, fitatu-mcp --demo (or FitatuTools.demo()) serves a small made-up diary kept in memory. For Claude Desktop, each GitHub release has fitatu- .mcpb, installed with a double click (log in with fitatu-api login first). Without installing anything, uvx --from "fitatu-api[mcp]" fitatu-mcp runs the server. It is listed in the MCP Registry as io.github.Jezue/fitatu-api (server.json). For Hermes Agent and other hosts that read Agent Skills, skills/fitatu-diary/SKILL.md tells the agent how to set the server up and use its tools well.

The host's permission prompt is the confirmation step, so keep it on for the destructive tools. Claude Desktop, uvx and what the server does: docs/AGENTS.md.

What it covers

FitatuLibrary, which wraps most of these as *_via_api methods that return {"status": ...} instead of raising, is deprecated and will be removed in 1.0: for results that never raise use FitatuTools ({"ok": true, "data": ...}), otherwise the client. Every public call with its stability is listed in docs/API_REFERENCE.md.

Free and Premium accounts

Nearly everything works on an account without Fitatu Premium. Fitatu answers 403 without it to (checked live 2026-10-15):

• `summary.get_nutrient_by_d