Mealie MCP

An MCP server that exposes a self-hosted Mealie instance to MCP clients like Claude — recipes, meal plans, shopping lists, and organizers (categories/tags).

What it does

• Recipes — list/search, get details, create, import from a URL, update, delete
• Meal Plans — get today's meals, list a date range, create/delete entries, add a random recipe
• Shopping Lists — list, get, create, delete, add a recipe's ingredients, add a single item, check off items
• Organizers — list categories and tags
• Utilities — get a recipe's nutrition info

Project layout

src/mealiemcp/
├── app.py            # FastMCP instance + auth setup
├── config.py         # environment variable loading
├── client.py         # Mealie HTTP client factory
├── security.py       # input validation (slug/id allowlists, SSRF guard)
├── audit.py          # logs which tool was called, by whom, and when
├── recipes.py         ┐
├── meal_plans.py       ├─ tool modules, one per Mealie domain
├── shopping_lists.py   │
├── organizers.py      ┘
└── server.py          # registers tool modules, entry point (main())
tests/                  # unit tests (pytest)

Setup

Requires uv.

uv sync
cp .env.example .env  # fill in your Mealie URL and API token
uv run mealiemcp

Run the tests with:

uv run pytest

Environment variables (see src/mealiemcp/config.py for details):

Variable	Purpose
MEALIE_BASE_URL	URL of your Mealie instance
MEALIE_API_TOKEN	Mealie API token this server uses to call Mealie
MCP_TRANSPORT	stdio (default, for local clients like Claude Desktop/Code) or streamable-http (to expose over a network)
MCP_HOST / MCP_PORT	Bind address/port when using streamable-http
MCP_AUTH_TOKEN	Bearer token remote clients must present — required when MCP_TRANSPORT isn't stdio
MCP_AUTH_TOKEN_EXPIRES_AT	YYYY-MM-DD (UTC) — MCP_AUTH_TOKEN stops being accepted after this date, forcing periodic rotation. Required alongside MCP_AUTH_TOKEN

A Dockerfile is included for running in streamable-http mode behind a reverse proxy.

Auth model

This is designed for a single user running their own instance, not a multi-tenant service. Remote access is a single shared bearer token (MCP_AUTH_TOKEN) rather than full OAuth — proportionate for one person's personal Mealie server. To limit the blast radius of a leaked token:

• It has a hard expiry (MCP_AUTH_TOKEN_EXPIRES_AT) and must be rotated periodically
• Every tool call is logged (tool name, authenticated client, success/failure, duration) via audit.py, so a misused token leaves a trace

License and disclaimer

This project is free to use, for any purpose, with no warranty of any kind. The author assumes no liability for any use of this software or any consequences arising from it — you use it entirely at your own risk. See the LICENSE file for the full terms.

This entire codebase was generated by AI. It has only been tested through the author's personal use against their own Mealie instance and has not been independently audited or reviewed. Review the code yourself before relying on it, especially before exposing it to a network.