fitatu_library

<p align="center">
  <img src="https://raw.githubusercontent.com/Jezue/fitatu_library/main/docs/assets/banner.png" alt="fitatu-api: your Fitatu food diary for AI agents (unofficial)" width="100%">
</p>

# fitatu-api

<!-- mcp-name: io.github.Jezue/fitatu-api -->

![PyPI](https://img.shields.io/pypi/v/fitatu-api)
![Python](https://img.shields.io/pypi/pyversions/fitatu-api)
![Status](https://img.shields.io/badge/status-alpha-orange)
![License](https://img.shields.io/badge/license-MIT-green)
![CI](https://github.com/Jezue/fitatu_library/actions/workflows/ci.yml/badge.svg)

An unofficial Python client for the API of [Fitatu](https://www.fitatu.com), 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](https://github.com/cyberjunky/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).

```bash
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

```bash
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](#authentication--session-file).

```python
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"]["measureId"], 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](https://github.com/Jezue/fitatu_library/blob/main/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](https://github.com/Jezue/fitatu_library/blob/main/docs/PLANNER.md#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.

```python
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](https://github.com/Jezue/fitatu_library/blob/main/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`):

```bash
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](https://github.com/Jezue/fitatu_library/blob/main/docs/AGENTS.md#remote-http-and-docker).

Without an account, `fitatu-mcp --demo` (or `FitatuTools.demo()`) serves a small made-up diary
kept in memory. For Claude Desktop, each [GitHub release](https://github.com/Jezue/fitatu_library/releases/latest)
has `fitatu-<version>.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](https://registry.modelcontextprotocol.io) as
`io.github.Jezue/fitatu-api` (`server.json`). For Hermes Agent and other hosts that read
[Agent Skills](https://agentskills.io), [`skills/fitatu-diary/SKILL.md`](https://github.com/Jezue/fitatu_library/blob/main/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](https://github.com/Jezue/fitatu_library/blob/main/docs/AGENTS.md#mcp).

## What it covers

| Area | Client (`FitatuApiClient`) | Agent tools |
|---|---|---|
| Food diary | `client.planner`: read a day, add products, recipes, custom rows and search hits, update, move, copy, remove; the day's note | `get_day`, `add_food`, `add_foods`, `add_custom_item`, `update_item`, `move_item`, `copy_meal`, `preview_removal`, `remove_items`, `set_note` |
| Activities | `planner.add_activity` / `remove_activity`, `client.activities` (catalog, search, recent) | `search_activity`, `add_activity`, `remove_activity` |
| Foods | `search_food`, `get_product_details`, `get_recipe`, recipe catalog and its search, `client.foods` (favourites, recent) | `search_food`, `search_recipes`, `get_recipe`, `find_by_barcode`, `get_food_measures`, `get_recent_foods`, `get_favorite_foods`, `set_favorite` |
| The user's own foods | `search_user_food`, `create_product`, `update_product`, `delete_product`, `create_recipe`, `update_recipe`, `delete_recipe` | `get_my_foods`; `create_food`, `update_food`, `delete_food` and the recipe tools for the user's own private foods only |
| Measurements | `client.measurements`: weight and body sizes per day, history, charts | `get_weight_history`, `get_body_measurements`, `get_measurement_history`, `log_weight`, `log_measurements` |
| Water | `client.water` | `get_water`, `set_water` |
| Summary and export | `client.summary`: range totals, nutrient per day, top products, diary export | `get_range_summary`, `get_progress`, `get_top_foods`, `get_report`, `get_shopping_list` (worked out from the planned rows) |
| Fasting and habits | `client.fasting` (schemes, eating periods per day), `client.habits` (catalog, the user's habits, good days); read only | `get_fasting`, `get_habits`, `get_good_days` |
| Goals and settings | `client.user_settings`: targets, BMR/TMR, profile | `get_targets`, `set_targets` (the manual or automatic goal, macro split, glass size), `get_profile` (height, weight, goal, BMI, Premium; nothing that identifies the user) |
| Catalog writes | `create_recipe(shared=True)`, `set_product_proposal`, dupli