🍲 Better Mealie MCP

An MCP server exposing every Mealie API endpoint — all 250+ operations, none excluded. Manage recipes, meal plans, shopping lists, households and more from any AI assistant, in natural language.

Built with FastMCP from_openapi: tools are generated straight from Mealie's OpenAPI spec, so the server stays in sync with Mealie and nothing is hand-maintained. See TOOLS.md for the full tool list.

💬 What can you do with it?

Related MCP server: Mealie MCP Server

🧙 Setup Wizard

→ Open the Setup Wizard

🚀 Setup

Docker (GHCR image):

docker pull ghcr.io/djwmarcx/better-mealie-mcp
docker run -i --rm \
  -e MEALIE_BASE_URL=http://host.docker.internal:9925 \
  -e MEALIE_API_TOKEN=... \
  ghcr.io/djwmarcx/better-mealie-mcp            # stdio; add `--http 8000` for HTTP

Images are published on each release, tagged <mealie-version> and latest. Inside a container, localhost is the container — point MEALIE_BASE_URL at host.docker.internal (macOS/Windows) or your host's LAN IP (Linux).

From source:

git clone https://github.com/djwmarcx/better-mealie-mcp
cd better-mealie-mcp
uv sync                     # install deps
cp .env.example .env        # then edit .env with your Mealie URL + token

Auth (set in .env or the environment):

Groups are the first path segment (recipes, households, admin, groups, organizers, users, explore, foods, units, auth, comments, media, shared, app, parser, utils). Unset = all 259 tools. INCLUDE wins if both are set. The Setup Wizard has a checkbox picker that fills MEALIE_INCLUDE_TAGS for you.

▶️ Run

uv run better-mealie-mcp             # stdio transport (for MCP clients)
uv run better-mealie-mcp --http 8000 # streamable-http on 127.0.0.1:8000
uv run server.py                     # same server, back-compat entry
fastmcp run fastmcp.json             # via FastMCP project config (stdio)
fastmcp run fastmcp-http.json        # via FastMCP project config (http)

In --http mode the bind address comes from MCP_HOST (default 127.0.0.1; the Docker image sets 0.0.0.0 so -p port mapping works).

🧪 Test against a local Mealie (Docker)

docker run -d --name mealie -p 9925:9000 \
  -e ALLOW_SIGNUP=true -e BASE_URL=http://localhost:9925 -e TZ=UTC \
  ghcr.io/mealie-recipes/mealie:latest

Default admin login: changeme@example.com / MyPassword.

📝 Notes

• Exposing every endpoint is a lot of tools — a lot of idle context. Most clients handle it, but if yours caps tool counts or you want a leaner context, use FastMCP's tool-search or filter by tag — ask and it can be wired in.

Versioning

This MCP's version mirrors the Mealie version its spec targets — MCP 3.20.1 ⇒ Mealie v3.20.1. The server advertises it to clients, and VERSIONS.md maps every release to its Mealie version and date.

openapi.json is a vendored copy of Mealie's spec. The update-spec workflow runs daily and auto-tracks the latest stable Mealie release (mealie:latest): it boots that image, reads its real version from /api/app/about (MEALIE_VERSION), pulls /openapi.json, regenerates TOOLS.md + counts, and — only when the spec actually changed — bumps the version and opens a pull request (main is protected, so every change lands via PR). When that PR merges, release-on-spec cuts a release (spec attached, notes listing added/removed tools). Volatile server-clock defaults are stripped so an unchanged run is a true no-op.

To freeze on one release instead of tracking latest, set MEALIE_TAG_DEFAULT in the workflow to a specific tag (e.g. v3.20.1), or run it manually with a mealie_tag input (latest, nightly, or any tag).

• A few endpoints (list_auth_oauth*) return 500 unless OIDC is configured on the Mealie side — that's Mealie behavior, not the server.