\n Left: installs the add-on (runs myMeal). Right: installs the HACS integration (entities, calendar, voice). \n Most people want both — see Home Assistant.\n
\n\n# myMeal\n\n[](https://github.com/Amantux/mymeal/actions/workflows/ha-validate.yml)\n[](https://github.com/Amantux/mymeal/actions/workflows/ci.yml)\n[](https://hacs.xyz/docs/faq/custom_repositories)\n[](https://www.home-assistant.io/addons/)\n[](https://www.home-assistant.io/)\n[](LICENSE)\n\n**Self-hosted recipes, AI meal planning & smart shopping lists — with a\nHome Assistant cooking assistant built in.**\n\nmyMeal is a privacy-first, self-hosted kitchen companion. Keep your recipe\ncollection, let an AI help you plan the week and cook, track what's in your\nand generate consolidated shopping lists — all runnable standalone or as\na Home Assistant add-on with voice control through Assist.\n\n> **Status:** all five milestones shipped — core recipe management, AI recipe\n> import + pluggable providers, meal planning, smart shopping lists, the\n> conversational cooking agent, the MCP server, and the Home Assistant\n> integration. See the [CHANGELOG](CHANGELOG.md).\n\n## Highlights (target feature set)\n\n- 📖 **Recipe manager** — structured ingredients & steps, images, categories,\n tags, favorites, fast search.\n- 🤖 **Pluggable AI** — Claude, Ollama, or OpenAI behind one interface. Import a\n recipe from a URL or pasted text, ask \"what can I cook with what I have\", and\n generate weekly meal plans.\n- 🗓️ **Meal planning** — a weekly planner that also feeds your calendar.\n- 🧺 **Inventory-aware** — with the companion [Edibl](https://github.com/Amantux/edibl) app connected, get suggestions ranked by what's actually on hand. myMeal itself stores no pantry; Edibl owns inventory.\n- 🛒 **Smart shopping lists** — auto-built from your plan, deduped and grouped by\n aisle.\n- 💬 **Cooking agent** — chat with an assistant that helps you build and cook\n recipes.\n- 🔌 **Home Assistant native** — an MCP server exposes tools to Assist so you can\n ask \"what's for dinner?\" and manage your list by voice.\n\n## Architecture\n\n```\nbackend/ Flask API (app factory, /api/v1), SQLAlchemy models, MCP server\nfrontend/ Vue 3 + Vite SPA (served by the backend)\ncustom_components/ Home Assistant (HACS) integration — config flow, sensors, calendar, services, card\nmymeal/ Home Assistant add-on config\nDockerfile Multi-stage build (frontend → python runtime)\n```\n\nThe backend serves both the JSON API under `/api/v1` and the built SPA. Auth is\nJWT by default, or disabled (`MYMEAL_DISABLE_AUTH=true`) when running behind\nHome Assistant ingress, which already authenticates the user.\n\n## Running\n\n### Docker (standalone)\n\n```bash\ndocker compose up --build\n# → http://localhost:7850\n```\n\nSet a strong `MYMEAL_SECRET_KEY` in `docker-compose.yml` before exposing it.\n\n### Local development\n\n```bash\n# Backend\ncd backend\npip install -r requirements.txt\npython run.py # http://localhost:7850\n\n# Frontend (separate terminal, proxies /api to :7850)\ncd frontend\nnpm install\nnpm run dev # http://localhost:5173\n```\n\n## Home Assistant\n\nmyMeal ships **two independent install paths**. They are complementary, not\nalternatives — the add-on runs the app, the integration surfaces it as entities.\n\n### Path 1 — the add-on (runs myMeal inside HA)\n\n[](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FAmantux%2Fmymeal)\n\nOne click adds the repository to your Home Assistant. Then install **myMeal**\nand click **Open Web UI**.\n\n\nManual alternative\n\n**Settings → Add-ons → Add-on Store → ⋮ → Repositories → Add**\n\n```\nhttps://github.com/Amantux/mymeal\n```\n\n\n**You will not be asked to sign in.** Ingress is enabled (`ingress: true`,\n`ingress_port: 7850`) and the add-on ships `disable_auth: true` by default:\nHome Assistant has already authenticated you at the ingress layer, so a second\nlogin would be pure friction. The frontend asks the backend directly\n(`GET /api/v1/misc/auth-mode`) whether sign-in is required rather than inferring\nit, so a transient error can never bounce you to a login screen inside HA. The\nMCP server is exposed on port `7851` for the Home Assistant MCP Client.\n\n> Running myMeal **outside** HA? Auth stays fully on — `disable_auth` only flips\n> in the add-on. Never set `MYMEAL_DISABLE_AUTH=true` on anything reachable from\n> an untrusted network: it binds every request to a single local user.\n\n### Path 2 — the HACS integration (entities, calendar, voice)\n\n[](https://my.home-assistant.io/redirect/hacs_repository/?owner=Amantux&repository=mymeal&category=integration)\n\nOne click opens it in HACS (requires HACS installed). Then **Download** →\nrestart HA → **Settings → Devices & Services → Add Integration → myMeal**.\n\n\nManual alternative\n\n**HACS → ⋮ → Custom repositories** → add `https://github.com/Amantux/mymeal`\nwith category **Integration**, then download it.\n\n\nIf you installed the add-on, it advertises itself via Supervisor discovery and\nthe integration should offer to configure itself with no URL or token typing.\n\nYou get:\n\n| Kind | What |\n|---|---|\n| Sensors | today's meals, shopping-list count |\n| Calendar | your meal plan as a native HA calendar entity |\n| Services | `add_to_shopping_list`, `plan_week`, `whats_for_dinner` |\n| Voice | Assist sentences — *\"what's for dinner?\"*, *\"add milk to my shopping list\"* |\n| Lovelace | `mymeal-card.js` dashboard card |\n\n### Pending external steps\n\nThese require action outside this repo and are **not** done:\n\n- **Brand icons** — the `mymeal` domain is not yet registered in\n [home-assistant/brands](https://github.com/home-assistant/brands), so HA shows\n a generic icon. That needs a PR against that upstream repo; the `brands` check\n is explicitly ignored in `ha-validate.yml` rather than silently passing.\n- **Default HACS listing** — myMeal installs as a *custom repository*. Inclusion\n in the default HACS store is a separate application to HACS.\n\n## Configuration\n\nAll configuration is via `MYMEAL_`-prefixed environment variables:\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `MYMEAL_SECRET_KEY` | `change-me…` | JWT signing key (set in production) |\n| `MYMEAL_DISABLE_AUTH` | `false` | Single-tenant mode behind a trusted proxy / HA ingress |\n| `MYMEAL_ALLOW_REGISTRATION` | `true` | Allow public sign-up |\n| `MYMEAL_DATA_DIR` | `./data` | SQLite DB + uploaded images |\n| `MYMEAL_PORT` | `7850` | HTTP port |\n| `MYMEAL_AI_PROVIDER` | _(blank)_ | `claude` \\| `ollama` \\| `openai` (AI features) |\n\n## Development\n\n```bash\ncd backend && ruff check . && pytest -q # lint + tests\ncd frontend && npm run build # type/build check\n```\n\n## License\n\n[AGPL-3.0](LICENSE). (myMeal is original, clean-room software; the license\nchoice mirrors the project owner's other self-hosted tools and can be changed.)\n"}
![\"myMeal](\"docs/banner.png\")
\n![\"Add](\"https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg\")
\n \n ![\"Add](\"https://my.home-assistant.io/badges/hacs_repository.svg\")
\n