mealie-mcp

A Model Context Protocol (MCP) server for Mealie, the self-hosted recipe manager and meal planner.

Lets MCP clients like Claude Code, Claude Desktop or Codex work with your recipe collection: search and read recipes with their ingredients and steps, import new ones from a website, keep tags and categories tidy, plan meals, build shopping lists from those plans, and record what was actually cooked.

Fifty-two tools is the ceiling, not the floor: MEALIE_ALLOW_TOOLS=essential registers a curated eight instead, and a model picks the right tool far more reliably from eight than from fifty-two — see choosing which tools load.

Mealie's REST API has 259 operations across 175 paths. This server exposes 52 tools, chosen so that the common tasks are one call and the dangerous surface is not reachable at all. Verified against Mealie v3.25.0; the source of truth for every request shape is the GET /openapi.json of a running instance, not the published documentation, which is out of date in several places.

What makes it different

Fifty-two curated tools out of 259 API operations. Mealie's REST API is far larger than a model should reach into; what is here covers the common tasks in one call — search, read and import recipes, keep tags and categories tidy, plan meals, build shopping lists, manage cookbooks and ratings.

update_recipe uses PATCH, not PUT. Mealie's replace route silently drops recipe fields that were not sent; only the fields you name change here.

The dangerous surface is unreachable. No admin routes, no token minting, no webhooks and no outbound-HTTP triggers, whatever the token would allow.

Requirements

• Node.js 22 or newer
• A Mealie instance and an API token from Settings → API Tokens

Configuration

The two booleans are compared against the literal string true, so a typo leaves them off — check the startup line on stderr, which reports the mode in effect.

The token is removed from the process environment once it has been read, so child processes cannot pick it up out of /proc/<pid>/environ.

Choosing which tools load

MEALIE_ALLOW_TOOLS and MEALIE_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of eight: search_recipes, get_recipe, import_recipe_from_url, create_recipe, get_todays_meals, create_mealplan_entry, list_shopping_lists, add_recipe_to_shopping_list.

MEALIE_ALLOW_TOOLS=essential
MEALIE_ALLOW_TOOLS=search_recipes,get_recipe,import_recipe_from_url
MEALIE_DENY_TOOLS=delete_*

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under MEALIE_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add mealie \
  -e MEALIE_URL=https://mealie.example.com \
  -e MEALIE_API_TOKEN=… \
  -- npx -y @ni-c/mealie-mcp

Claude Desktop

The same entry works in any MCP client that takes a JSON config:

{
  "mcpServers": {
    "mealie": {
      "command": "npx",
      "args": ["-y", "@ni-c/mealie-mcp"],
      "env": {
        "MEALIE_URL": "https://mealie.example.com",
        "MEALIE_API_TOKEN": "…"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.mealie]
command = "npx"
args = ["-y", "@ni-c/mealie-mcp"]

[mcp_servers.mealie.env]
MEALIE_URL = "https://mealie.example.com"
MEALIE_API_TOKEN = "…"

MCP Inspector

To poke at the tools interactively:

npx @modelcontextprotocol/inspector npx -y @ni-c/mealie-mcp

Docker

docker run --rm -i \
  -e MEALIE_URL=https://mealie.example.com \
  -e MEALIE_API_TOKEN=… \
  ghcr.io/ni-c/mealie-mcp

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches mealie-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{
  "mcpServers": {
    "mealie": {
      "command": "npx",
      "args": ["-y", "@ni-c/mealie-mcp"],
      "env": { "MEALIE_ALLOW_TOOLS": "essential" },
      "denyTools": ["delete_*"]
    }
  }
}

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

Every tool declares an outputSchema and answers with structuredContent alongside the text block, so a client can use the result without parsing prose. Nine tools that answered with a sentence — "Deleted the recipe with id …" — now answer with the fields as well.

Most tools carry untrusted: true and source: "mealie" as fields: recipes are routinely scraped from arbitrary websites and comments come from other users of the instance. The ten without it answer with an id this server was given — or, for get_about, a version string and the permission flags of the account it authenticates as, which are facts the model should act on.

Mealie's records are described as open objects with the top-level keys this server builds. A self-hosted Mealie is any release, and the SDK validates each result against its schema before it goes out — a strict shape would turn a field a release adds into a tool that fails outright.

Recipes — search_recipes, get_recipe, suggest_recipes, create_recipe, update_recipe, duplicate_recipe, set_recipe_last_made, delete_recipe 🔒