Mealie MCP Server

Docker-hosted MCP server for Mealie. It gives an AI agent the tools to read a cookbook (e.g. a PDF), extract the recipes (translating them if needed) and store them in Mealie — then verify its own work.

Built against Mealie API v3.19.2. Transport: SSE (http://localhost:8001/sse) — persistent container, no subprocess spawning.

It deliberately covers only the endpoints that serve the cookbook → Mealie workflow (recipes, recipe images, organizers, foods, units) plus read endpoints for verification. The rest of the Mealie API is intentionally omitted.

Prerequisites

• Docker (with Compose)

• A reachable Mealie instance

• A Mealie API token (or a username/password)

Related MCP server: mcp-mealie

Generate an API token

In Mealie: avatar → Settings → API Tokens → Create (or /user/profile/api-tokens). Copy the token — it is shown only once.

Quick Start

git clone https://github.com/NigelVanHattum/mealie-mcp.git
cd mealie-mcp

# Configure credentials
mkdir -p ~/.config/mealie-mcp
cat > ~/.config/mealie-mcp/config.json << 'EOF'
{
  "base_url": "https://mealie.example.com",
  "api_token": "your-api-token-here",
  "verify_ssl": true
}
EOF

# Start the server
docker compose up -d

The server runs at http://localhost:8001. Verify:

curl http://localhost:8001/health
# {"status": "ok"}

Connect to Claude

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mealie": {
      "url": "http://localhost:8001/sse"
    }
  }
}

Restart Claude Desktop, then try: "Check my Mealie connection" → it calls get_current_user.

Claude Code

claude mcp add mealie --url http://localhost:8001/sse

Configuration

Loaded in this order (first found wins):

The server authenticates to Mealie with API keys only — there is no username/password path.

Exposure & security

The MCP API itself is unauthenticated: /sse, /messages/ and /health have no inbound auth. Anyone who can reach the port can call every tool — including create_recipe, overwrite_recipe and delete_recipe — using the server's Mealie API key.

So treat the server as a private backend: let Obot (or your MCP host) connect to it over localhost or a private/Docker network, and do not expose the port to the public internet. If it must traverse an untrusted network, put a reverse proxy with authentication in front of it. Transport is SSE; Streamable HTTP can be added if your host prefers it.

Recommended agent workflow

1. get_current_user — confirm the token works and note the active group.

2. list_recipes with search — check the recipe doesn't already exist.

3. create_recipe — one call stores a full recipe. Translate fields to the target language (e.g. Dutch) before calling. Pass ingredients and instructions as plain strings; pass categories / tags / tools as names (they are created automatically if missing).

4. set_recipe_image_from_url (or upload_recipe_image) — give the recipe a picture. Optional, but a recipe without one looks empty in Mealie.

5. get_recipe with the returned slug — verify the stored content.

create_recipe and update_recipe merge onto the recipe's current state, so they never wipe fields you didn't provide. When you want a clean re-import, use overwrite_recipe instead: it replaces all recipe content explicitly — every content field you omit is cleared (identity, settings and image are kept).

Tools Reference

create_recipe — key fields

name (required), description, ingredients (string[]), instructions (string[]), recipeYield, servings, prepTime, cookTime, totalTime, categories (string[]), tags (string[]), tools (string[]), nutrition (object), orgURL, extras (object).

Ingredients are stored as free text by default — ideal for cookbook imports. For structured ingredients, pass an object per line ({quantity, unit, food, note}) and manage foods / units with their tools.

Recipe images

Images are set on an existing recipe, by slug — create the recipe first. Both write tools replace whatever image the recipe already had.

imageBase64 takes raw base64 or a data URI (data:image/png;base64,…). The format is detected from the image's magic bytes (jpg, png, webp, gif, bmp, heic, avif); pass extension only if detection fails. Base64 inflates payloads by ~33%, so keep uploads to a few MB — use the URL tool where you can.

Mealie re-encodes every image to WebP and stores three sizes. A recipe's image field is a cache-busting version key, not a path, so all three tools re-read the recipe and return the id, the new version key and the resulting media URLs:

{
  "slug": "pannenkoeken",
  "recipeId": "a1b2c3d4-…",
  "imageVersion": "GhIjKl",
  "hasImage": true,
  "imageUrls": {
    "original": "https://mealie.example.com/api/media/recipes/a1b2c3d4-…/images/original.webp",
    "min":      ".../min-original.webp",
    "tiny":     ".../tiny-original.webp"
  }
}

Those media URLs are served by Mealie's /api/media routes, which do not require the API token — anyone who can reach the Mealie instance can fetch them.

hasImage is checked, not assumed. Mealie's URL endpoint returns success and bumps the version key even when its own download failed — it swallows the fetch error — so a 2xx there does not mean an image was stored. The most common cause is Mealie's SSRF guard: it refuses URLs that resolve to a private or local address, which rules out serving the image from another host on your LAN. So:

• hasImage reflects whether the stored file actually serves, not the version key.

• set_recipe_image_from_url raises when nothing was stored, with the likely causes, instead of reporting a false success.

• If the recipe already had an image, a failed download leaves the old one in place. That case can't be proven either way, so the result carries imageChanged: false plus a warning rather than an error.

Development

pip install -e ".[dev]"
pytest

# Build image locally (tests run in the build stage — build fails if tests fail)
docker build -t mealie-mcp .

docker compose up

API Reference

Interactive docs for your instance: https://<your-mealie>/docs · OpenAPI: https://<your-mealie>/openapi.json