MealMCP

English · Français

Meal planning, shopping and pantry stock for a household, with a built-in MCP server so an AI assistant can drive it.

• Planning: meals per day, from a recipe or free text. Household settings (people eating, which meals on which weekdays) highlight the empty slots to fill.

• Recipes: ingredients (staples and "to taste" items are never bought), servings, prep and cook time, tags (air fryer, quick, no shopping), structured steps (appliance, temperature, duration), the equipment they need, and availability against your stock.

• Equipment: the appliances and utensils you own. Recipes needing something you do not have are flagged.

• Shopping: a list generated from the meal plan (needs − stock + products below their threshold), manual additions, and putting purchases away into stock.

• Stock: by location (fridge, freezer, pantry), expiry dates, low-stock alerts, "plenty of it" quantities, per-product conversions (1 sweet potato = 300 g, 1 tbsp = 15 ml) and aliases (receipt wording). Recipes can be suggested to use up what expires soon.

• Budget: record purchases (by hand, from a receipt via an AI, or when you finish shopping), a monthly budget with a projection, spending by category / shop / month, and cost estimates for recipes, the week's meals and the shopping list, from the prices of what you bought.

• Live dashboard: the web UI refreshes by itself when something changes elsewhere, for example when an AI edits your stock through MCP.

• Installable (PWA): add it to your phone's home screen for a full-screen app (needs HTTPS, see below).

• Bilingual: English and French UI (language switcher at the top right, browser language by default). MCP tool descriptions are in English.

Architecture

server/src
  db/         Drizzle schema + SQLite, migrations applied at startup
  domain/     Zod input schemas, units, dates, errors
  auth/       accounts, sessions, households, OAuth server for MCP
  services/   all the business logic (bound to one household)
  api/        REST adapter (used by the web UI)
  mcp/        MCP adapter (used by AI clients)
web/src       React + Vite + Tailwind UI (messages in web/src/i18n)

The REST API and the MCP server are two thin adapters over the same services: a business rule is written once, in services/.

Quantities are stored in a base unit (g, ml, "piece"); kg, l and cl are converted on input.

Related MCP server: mise-mcp

Development

npm install
npm run dev

UI on http://localhost:5173, backend on http://localhost:3000.

To add a UI language, add a file next to web/src/i18n/fr.ts (it must define every key of en.ts) and register it in web/src/i18n/index.tsx.

CI/CD

• ci.yml: on every push and pull request, build (type-checks web + server), tests, then builds the Docker image and smoke-tests the container (access refused without an account, OAuth discovery, account creation).

• release.yml: after the tests, publishes the image to GitHub Container Registry; for a vX.Y.Z tag it also creates a GitHub Release. To release: git tag -a v0.2.0 -m v0.2.0 && git push origin v0.2.0.

• Dependabot updates npm dependencies, GitHub Actions and the base image.

Docker deployment

Copy .env.example to .env and set at least PUBLIC_URL (the real address of the app, over HTTPS if remote MCP clients must reach it), then:

docker compose up -d

This pulls the published image (ghcr.io/rem7474/mealmcp:latest). To pin a version, add MEALMCP_VERSION=0.1.0 to .env; to build from source, use docker compose up -d --build.

Then open the app: the first account created becomes the household owner.

The image (amd64 and arm64) is published on every push to main (tag main) and every vX.Y.Z tag (tags X.Y.Z, X.Y and latest).

The SQLite database lives in the mealmcp-data volume. If the app is exposed beyond your local network, put it behind an HTTPS reverse proxy and set PUBLIC_URL and TRUST_PROXY (see .env.example).

Accounts and households

• A household groups recipes, meal plan, shopping list and stock. Every row belongs to a household and the services always filter on it, so two households never see each other's data.

• The first account creates a household and owns it. The owner then invites others (Account tab) with a single-use code valid for 7 days. ALLOW_REGISTRATION=true also lets strangers create their own households.

• Passwords are hashed with scrypt, sessions use HttpOnly/SameSite=Lax cookies, tokens and codes are stored hashed, and login attempts are rate-limited.

• No password reset by email: the app does not send mail. If someone forgets their password, delete their user row from the database and have them sign up again.

Connecting an AI (MCP)

Endpoint: POST /mcp (Streamable HTTP transport, stateless). It always acts on the signed-in person's household.

OAuth 2.1 (recommended): the server is its own authorization server (discovery metadata, dynamic client registration, PKCE S256, one-hour access tokens and refresh tokens rotated on every use). A compatible client such as Claude only needs the address PUBLIC_URL/mcp: it opens the sign-in page, you allow access, done. Granted access can be revoked from the Account tab. Note that OAuth discovery requires PUBLIC_URL to be HTTPS (or localhost).

Personal token: for scripts or clients without OAuth, create a token in the Account tab, then for example with Claude Code:

claude mcp add --transport http mealmcp http://localhost:3000/mcp --header "Authorization: Bearer mmcp_YOUR_TOKEN"

The same token works on the REST API (/api). To try the OAuth flow locally, use the built app (npm run build && npm start) rather than npm run dev.

Money: amounts you send are decimals in the household currency (2.49), amounts you receive are integers in cents (249). Writes made through MCP (or the API) are pushed to open dashboards over Server-Sent Events (GET /api/events), so there is nothing to refresh.

Tools: stock (list_stock, add_stock, update_stock_item, consume_stock, remove_stock_item, get_stock_alerts), products (list_products, update_product, add_product_alias, remove_product_alias), recipes (list_recipes, get_recipe, create_recipe, update_recipe, delete_recipe, check_recipe_availability, suggest_recipes_to_use_up), equipment (list_equipment, add_equipment, update_equipment, remove_equipment), meal plan (list_meal_plan, plan_meal, remove_planned_meal, cook_planned_meal, list_planning_slots), shopping (list_shopping_list, add_shopping_item, check_shopping_item, remove_shopping_item, generate_shopping_list, complete_shopping), household (get_household_settings, set_household_settings), bulk variants (add_stock_bulk, create_recipes_bulk, plan_meals_bulk, add_shopping_items_bulk), budget (record_expense, list_expenses, get_expense, delete_expense, get_spending_summary, get_budget_status, set_budget, set_product_price, estimate_recipe_cost, estimate_meal_plan_cost, estimate_shopping_list_cost).

License

MIT