{
"markdown": "# mealie-mcp\n\n\n\n[](https://github.com/ni-c/mealie-mcp/actions/workflows/ci.yml)\n[](https://scorecard.dev/viewer/?uri=github.com/ni-c/mealie-mcp)\n![\"Socket](\"https://socket.dev/api/badge/npm/package/@ni-c/mealie-mcp\")
\n[](https://glama.ai/mcp/servers/ni-c/mealie-mcp)\n
\n[](https://www.npmjs.com/package/@ni-c/mealie-mcp)\n[](https://github.com/ni-c/mealie-mcp/pkgs/container/mealie-mcp)\n[](https://mcp-hub.ni-c.de)\n
\n[](https://mealie-mcp.ni-c.de)\n[](https://github.com/sponsors/ni-c)\n\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for\n[Mealie](https://mealie.io), the self-hosted recipe manager and meal planner.\n\nLets MCP clients like Claude Code, Claude Desktop or Codex work with your recipe\ncollection: search and read recipes with their ingredients and steps, import new ones\nfrom a website, keep tags and categories tidy, plan meals, build shopping lists from\nthose plans, and record what was actually cooked.\n\nFifty-two tools is the ceiling, not the floor: `MEALIE_ALLOW_TOOLS=essential`\nregisters a curated eight instead, and a model picks the right tool far more\nreliably from eight than from fifty-two — see\n[choosing which tools load](#choosing-which-tools-load).\n\n\n\n\n\n \n \n ![\"An](\"https://mealie-mcp.ni-c.de/architecture.svg\")
\n\n\nMealie's REST API has 259 operations across 175 paths. This server exposes **52\ntools**, chosen so that the common tasks are one call and the dangerous surface is\nnot reachable at all. Verified against **Mealie v3.25.0**; the source of truth for\nevery request shape is the `GET /openapi.json` of a running instance, not the\npublished documentation, which is out of date in several places.\n\n## What makes it different\n\n**Fifty-two curated tools out of 259 API operations.** Mealie's REST API is far\nlarger than a model should reach into; what is here covers the common tasks in one\ncall — search, read and import recipes, keep tags and categories tidy, plan meals,\nbuild shopping lists, manage cookbooks and ratings.\n\n**`update_recipe` uses PATCH, not PUT.** Mealie's replace route silently drops\nrecipe fields that were not sent; only the fields you name change here.\n\n**The dangerous surface is unreachable.** No admin routes, no token minting, no\nwebhooks and no outbound-HTTP triggers, whatever the token would allow.\n\n## Requirements\n\n- Node.js 22 or newer\n- A Mealie instance and an API token from **Settings → API Tokens**\n\n## Configuration\n\n| Variable | Required | Description |\n| ------------------------ | -------- | ---------------------------------------------------------------------------------- |\n| `MEALIE_URL` | yes | Base URL, e.g. `https://mealie.example.com` |\n| `MEALIE_API_TOKEN` | yes | Token from Settings → API Tokens. It acts as the user who created it. |\n| `MEALIE_READ_ONLY` | no | Exactly `true` registers the 18 read tools only |\n| `MEALIE_ACCEPT_LANGUAGE` | no | e.g. `de-DE`; localises unit and label names |\n| `MEALIE_INSECURE_TLS` | no | Exactly `true` accepts a self-signed certificate, scoped to this connection |\n| `MEALIE_ALLOW_TOOLS` | no | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset |\n| `MEALIE_DENY_TOOLS` | no | Same syntax; removed from whatever `MEALIE_ALLOW_TOOLS` left |\n| `ELICITATION` | no | `false` replaces the approval dialog with the two-call token. **Not prefixed** |\n\nThe two booleans are compared against the literal string `true`, so a typo leaves\nthem **off** — check the startup line on stderr, which reports the mode in effect.\n\nThe token is removed from the process environment once it has been read, so child\nprocesses cannot pick it up out of `/proc//environ`.\n\n### Choosing which tools load\n\n`MEALIE_ALLOW_TOOLS` and `MEALIE_DENY_TOOLS` take comma-separated tool names;\na trailing `*` matches a whole family. `essential` is a curated preset of\neight: `search_recipes`, `get_recipe`, `import_recipe_from_url`, `create_recipe`, `get_todays_meals`, `create_mealplan_entry`, `list_shopping_lists`, `add_recipe_to_shopping_list`.\n\n```sh\nMEALIE_ALLOW_TOOLS=essential\nMEALIE_ALLOW_TOOLS=search_recipes,get_recipe,import_recipe_from_url\nMEALIE_DENY_TOOLS=delete_*\n```\n\nAn entry that matches no tool aborts startup and names it, so a typo cannot\nsilently hide a tool — an absent tool is not something anyone traces back to an\nenvironment variable. A filtered tool is never registered, so it is absent from\n`tools/list` and unknown to `tools/call` alike, exactly like a write tool under\n`MEALIE_READ_ONLY`.\n\nIf you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de)\nis the other answer — its `/hub` endpoint replaces every server's tools with six\nmeta-tools.\n\n## Installation\n\n### Claude Code\n\n```sh\nclaude mcp add mealie \\\n -e MEALIE_URL=https://mealie.example.com \\\n -e MEALIE_API_TOKEN=… \\\n -- npx -y @ni-c/mealie-mcp\n```\n\n### Claude Desktop\n\nThe same entry works in any MCP client that takes a JSON config:\n\n```json\n{\n \"mcpServers\": {\n \"mealie\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ni-c/mealie-mcp\"],\n \"env\": {\n \"MEALIE_URL\": \"https://mealie.example.com\",\n \"MEALIE_API_TOKEN\": \"…\"\n }\n }\n }\n}\n```\n\n### Codex\n\n`~/.codex/config.toml`:\n\n```toml\n[mcp_servers.mealie]\ncommand = \"npx\"\nargs = [\"-y\", \"@ni-c/mealie-mcp\"]\n\n[mcp_servers.mealie.env]\nMEALIE_URL = \"https://mealie.example.com\"\nMEALIE_API_TOKEN = \"…\"\n```\n\n### MCP Inspector\n\nTo poke at the tools interactively:\n\n```sh\nnpx @modelcontextprotocol/inspector npx -y @ni-c/mealie-mcp\n```\n\n### Docker\n\n```sh\ndocker run --rm -i \\\n -e MEALIE_URL=https://mealie.example.com \\\n -e MEALIE_API_TOKEN=… \\\n ghcr.io/ni-c/mealie-mcp\n```\n\n### Through mcp-hub\n\nA client that cannot spawn a local process — ChatGPT connectors, Claude on the web,\nCursor, LibreChat — reaches mealie-mcp through [mcp-hub](https://mcp-hub.ni-c.de): one\ncontainer serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login\nbehind a single password and long-lived tokens for the clients that cannot do OAuth. Its\n`/hub` endpoint puts every server behind six meta-tools, so one connector reaches all of\nthem without N×tool schemas in the model's context, and it speaks both protocol revisions\n— a question this server asks travels through it to the person at the far end.\n\nIts `/config/mcp.json` uses Claude Code's format, so the entry is the one you already\nhave:\n\n```json\n{\n \"mcpServers\": {\n \"mealie\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ni-c/mealie-mcp\"],\n \"env\": { \"MEALIE_ALLOW_TOOLS\": \"essential\" },\n \"denyTools\": [\"delete_*\"]\n }\n }\n}\n```\n\n`allowTools` and `denyTools` there are the hub's **own** per-server filter, which is not\nthe same thing as `*_ALLOW_TOOLS` in `env` — the difference, and the mistake it invites,\nare in the [client guide](https://mealie-mcp.ni-c.de/guide/clients#through-mcp-hub).\n\n## Tools\n\nEvery tool declares an `outputSchema` and answers with `structuredContent`\nalongside the text block, so a client can use the result without parsing prose.\nNine tools that answered with a sentence — _\"Deleted the recipe with id …\"_ —\nnow answer with the fields as well.\n\nMost tools carry `untrusted: true` and `source: \"mealie\"` as fields: recipes are\nroutinely scraped from arbitrary websites and comments come from other users of\nthe instance. The ten without it answer with an id this server was given — or,\nfor `get_about`, a version string and the permission flags of the account it\nauthenticates as, which are facts the model should act on.\n\nMealie's records are described as open objects with the top-level keys this\nserver builds. A self-hosted Mealie is any release, and the SDK validates each\nresult against its schema before it goes out — a strict shape would turn a field\na release adds into a tool that fails outright.\n\n**Recipes** — `search_recipes`, `get_recipe`, `suggest_recipes`, `create_recipe`,\n`update_recipe`, `duplicate_recipe`, `set_recipe_last_made`, `delete_recipe` 🔒\n\n**Import** — `preview_recipe_url` (dry run, saves nothing), `import_recipe_from_url`,\n`import_recipe_from_html_or_json`, `import_recipe_from_image`\n\n**Organizing** — `list_organizers`, `create_organizer`, `update_organizer`,\n`delete_organizer` 🔒 — each takes `kind: tag | category | tool`\n\n**Ingredients** — `list_foods`, `create_food`, `merge_foods` 🔒, `list_units`,\n`create_unit`, `merge_units` 🔒, `parse_ingredients`\n\n**Meal plans** — `list_mealplans`, `get_todays_meals`, `create_mealplan_entry`,\n`create_random_meal`, `update_mealplan_entry`, `delete_mealplan_entry` 🔒\n\n**Shopping** — `list_shopping_lists`, `get_shopping_list`, `create_shopping_list`,\n`delete_shopping_list` 🔒, `add_shopping_list_items`, `update_shopping_list_items`,\n`delete_shopping_list_items` 🔒, `add_recipe_to_shopping_list`,\n`remove_recipe_from_shopping_list`\n\n**Cookbooks** — `list_cookbooks`, `get_cookbook`, `create_cookbook`,\n`delete_cookbook` 🔒\n\n**Notes and sharing** — `set_recipe_rating`, `add_recipe_comment`,\n`delete_recipe_comment` 🔒, `list_recipe_comments`, `list_recipe_timeline`,\n`create_timeline_event`, `list_share_tokens`, `create_share_token` 🔒,\n`delete_share_token` 🔒\n\n**Instance** — `get_about`\n\n🔒 asks a person through MCP elicitation — a dialog the model cannot answer on its\nbehalf. Where the client cannot show one it falls back to a two-call\n`confirm_token`. See\n[Asking a person](https://mealie-mcp.ni-c.de/guide/approval).\n\nRecipes can be addressed by slug or by UUID everywhere — Mealie splits its\nidentifier space between the two, and the tools resolve whichever they are given.\n\n## Not exposed, on purpose\n\nEverything under `/api/admin` (backups, restore, maintenance, user, group and\nhousehold management, email, AI provider settings), `/api/users/api-tokens` (a tool\nthat mints API credentials is privilege-escalation surface), the authentication\nroutes, user CRUD and passwords, webhooks, event notifications and recipe actions\n(all three trigger outbound HTTP from the instance), meal plan rules, migrations,\nseeders, invitations, bulk export and ZIP download, and asset and image uploads.\n\n`PUT /api/recipes/{slug}` is not exposed either: it replaces the entire 33-field\nrecipe object, so a partial update through it silently drops ingredients, steps and\ntags. `update_recipe` uses `PATCH`.\n\n## Safety\n\n- **Instance content is untrusted input.** Recipes are routinely scraped from\n arbitrary websites and comments come from other users, so every tool result that\n can contain instance content is prefixed with an explicit marker telling the model\n to treat it as data. This matters after the import too: the text stays in the\n database and comes back through `get_recipe`.\n- **The import tools make Mealie fetch, not this server.** URLs are restricted to\n `http`/`https`, and loopback and link-local hosts are refused — including the\n cloud metadata endpoints and the hostnames that resolve to them. Addresses are\n compared numerically, so an IPv4-mapped literal such as\n `[::ffff:169.254.169.254]` is caught too, and a hostname is resolved as well —\n best effort, since a name that does not resolve here is passed on. Private LAN\n addresses are passed on as of 0.1.2, but Mealie refuses them itself, so such an\n import fails there rather than here. See SECURITY.md for what the check does not\n cover, including `import_recipe_from_html_or_json`.\n- **Confirmation prompts quote no upstream text** — ids, counts and flags only.\n- **Responses are bounded**: oversized results drop whole items rather than cutting\n the JSON mid-string, and a response body is never read past 8 MB.\n- Redirects are refused so the token cannot be resent to another host.\n\nSee [SECURITY.md](SECURITY.md) for the trust model and how to report a\nvulnerability.\n\n## Documentation\n\nThe full guide, tool reference and security notes live at\n**[mealie-mcp.ni-c.de](https://mealie-mcp.ni-c.de)** (source in [`docs/`](docs/)).\n\n## Development\n\n```sh\nnpm install && npm test && npm run build\n```\n\n`scripts/verify-live.mjs` exercises all 52 tools against a **throwaway** Mealie\ninstance; the recipe for setting one up is in [CONTRIBUTING.md](CONTRIBUTING.md).\n\nThe architecture diagram and the social card are rendered from\n`docs/assets/architecture.source.svg` and `docs/assets/og.json` by\n`npm run assets`; CI fails if a rendered copy was edited by hand.\n\n## Releasing\n\nEverything is driven by a tag; there is no manual publish step.\n\n1. Move the `[Unreleased]` section of [CHANGELOG.md](CHANGELOG.md) to the new version\n and date it. The release workflow extracts that section with `awk`, so the\n `## [x.y.z]` heading shape matters.\n2. Bump `version` in `package.json`.\n3. `npm run lint && npm run build && npm run test:coverage`.\n4. Commit, then a **signed annotated** tag:\n\n ```sh\n git tag -s v0.1.1 -m \"v0.1.1\"\n git push origin main v0.1.1\n ```\n\n`release.yml` then verifies the tag matches `package.json`, publishes to npm over\n**Trusted Publishing** (OIDC — no npm token exists to leak) with provenance, syncs the\nversion into both `server.json` package entries, publishes to the MCP registry, and\ncuts the GitHub release from the changelog section. `ci.yml` pushes the multi-arch\ncontainer image to GHCR in parallel.\n\n## Contributing\n\nIssues, discussions and pull requests are welcome — see\n[CONTRIBUTING.md](CONTRIBUTING.md). For vulnerabilities please use\n[private reporting](https://github.com/ni-c/mealie-mcp/security/advisories/new)\nrather than a public issue; the policy is in [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © Willi Thiel\n",
"bytes": 15573,
"sha": "0ea4879090378e369889b5fee3b8cd11bbf4ab934cd292f2eec79c16b5cb89a2",
"repo_slug": "ni-c/mealie-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_ni_c_mealie_mcp_f50833fc/readme"
}