Mealie MCP Server

A security-conscious Model Context Protocol server for self-hosted Mealie instances.

It exposes recipe search and import, shopping lists, meal plans, organizers, ingredient parsing, OCR helpers, recipe images/assets, Chefkoch lookup, and a guarded bridge to non-sensitive Mealie OpenAPI operations.

Community project. Not affiliated with or endorsed by Mealie.

Security defaults

• Read-only by default: mutations require MEALIE_MCP_ALLOW_MUTATIONS=true.
• Fail-closed scopes: no write is allowed unless its path matches an explicit scope.
• Explicit confirmation: every helper that persists data and every generic write requires confirmed_by_user=true.
• Sensitive API denylist: admin, authentication, user, group, invitation, webhook, and household self-service endpoints remain blocked even when mutations are enabled.
• Outbound fetches off by default: URL imports and remote file sources require separate opt-in flags in addition to mutation scopes.
• SSRF protection: enabled remote sources must resolve to public HTTP(S) addresses; loopback, private, link-local, and other non-public destinations are rejected.
• Local-file confinement: multipart uploads may only read from the MCP data directory or explicitly configured local roots.
• Credential redaction: configured tokens and passwords are removed from reported errors.
• Bounded work: JSON/OpenAPI responses, local/remote sources, downloads, image pixels, pagination, and OCR runtime have limits.
• Transport safety: remote Mealie origins require HTTPS, and authenticated Mealie requests reject redirects.

Review SECURITY.md before enabling writes.

Requirements

• Python 3.11+
• uv
• A reachable Mealie instance (tested against Mealie OpenAPI v3.21.0)
• A Mealie long-lived API token, recommended
• Optional: Tesseract for OCR (tesseract-ocr plus the desired language packs)

Quick start

git clone https://github.com/bitmonster/mealie-mcp-server.git
cd mealie-mcp-server
uv sync --frozen
chmod +x run_mealie_mcp.sh

Create a long-lived token in Mealie under Profile → API tokens. Pass it through your MCP client environment; do not put it in source control.

Hermes Agent

mcp_servers:
  mealie:
    command: /absolute/path/to/mealie-mcp-server/run_mealie_mcp.sh
    env:
      MEALIE_BASE_URL: http://localhost:9000
      MEALIE_PUBLIC_URL: https://mealie.example.com
      MEALIE_API_TOKEN: "[REDACTED]"
      MEALIE_MCP_ALLOW_MUTATIONS: "false"
      MEALIE_MCP_MUTATION_SCOPE: none
      MEALIE_MCP_ALLOW_URL_IMPORTS: "false"
      MEALIE_MCP_ALLOW_REMOTE_SOURCES: "false"

Restart Hermes after changing MCP configuration, then run:

hermes mcp test mealie

Generic stdio MCP client

Configure the command as:

/absolute/path/to/mealie-mcp-server/run_mealie_mcp.sh

Set the environment variables shown in .env.example. The server reserves stdout for MCP JSON-RPC and writes startup errors to stderr.

Authentication

Preferred:

MEALIE_API_TOKEN=[REDACTED]

Optional fallback for local testing:

MEALIE_USERNAME=[REDACTED]
MEALIE_PASSWORD=[REDACTED]

The fallback performs a normal /api/auth/token login and caches the short-lived token in memory. Do not embed credentials in the repository or starter script.

Mutation scopes

Mutations require both:

MEALIE_MCP_ALLOW_MUTATIONS=true
MEALIE_MCP_MUTATION_SCOPE=<comma-separated scopes>

Scope	Allowed write areas
recipe_import	Recipe creation/PATCH, images, assets, duplicate, last-made, ZIP/image/URL imports
shopping	Shopping lists, items, bulk operations, recipe ingredients added to lists
mealplan	Meal-plan entries, random suggestions, and meal-plan rules
parser	Generic parser API mutations; the dedicated non-persisting ingredient parser does not require mutation mode
organizers	Categories, tags, foods, and units
cookbooks	Household cookbooks
comments	Recipe comments
timeline	Recipe timeline events and images
recipe_actions	Household recipe actions
all	Every non-sensitive mutation; use only for tightly trusted clients

Example for recipe imports and organizer cleanup:

MEALIE_MCP_ALLOW_MUTATIONS=true
MEALIE_MCP_MUTATION_SCOPE=recipe_import,organizers

Scopes do not override the sensitive-endpoint denylist or confirmation requirements. URL imports additionally require MEALIE_MCP_ALLOW_URL_IMPORTS=true. Remote image or asset sources additionally require MEALIE_MCP_ALLOW_REMOTE_SOURCES=true.

Main capabilities

The server currently registers 38 MCP tools, including:

• recipe search, lookup, suggestions, URL/text imports, duplication, last-made updates;
• image replacement, source asset upload, cover cropping, and cookbook-image OCR;
• shopping-list and meal-plan CRUD helpers using Mealie v3 full-model updates;
• organizer listing and ingredient parsing;
• Chefkoch search and recipe extraction;
• live OpenAPI catalog search;
• generic JSON/multipart requests and controlled binary downloads for non-sensitive operations.

Use mealie_api_operations before a generic OpenAPI call. It validates operation IDs, path/query parameters, required body fields, content type, sensitivity, confirmation, and mutation scope.

File and download configuration

Variable	Default	Purpose
MEALIE_MCP_DATA_DIR	~/.cache/mealie-mcp	Runtime data root
MEALIE_MCP_DOWNLOAD_DIR	$DATA_DIR/downloads	Controlled download directory
MEALIE_MCP_ALLOWED_LOCAL_ROOTS	empty	Additional local upload roots, separated by the OS path separator
MEALIE_MCP_MAX_DOWNLOAD_BYTES	100 MiB	Maximum binary download size
MEALIE_MCP_MAX_JSON_BYTES	10 MiB	Maximum JSON response size
MEALIE_MCP_MAX_OPENAPI_BYTES	20 MiB	Maximum OpenAPI response size
MEALIE_MCP_MAX_IMAGE_PIXELS	40,000,000	Maximum decoded image pixels
MEALIE_MCP_OCR_TIMEOUT	60 seconds	Tesseract timeout per OCR call
MEALIE_MCP_TIMEOUT	30 seconds	HTTP timeout
MEALIE_MCP_ALLOW_URL_IMPORTS	false	Allow Mealie to fetch validated public recipe URLs
MEALIE_MCP_ALLOW_REMOTE_SOURCES	false	Allow this MCP process to fetch validated public file URLs

Default local upload roots are $DATA_DIR/imports and the download directory. Add the narrowest possible absolute path when another client-managed media cache is needed.

Development

uv sync --frozen --all-groups
uv run python -m compileall -q mealie_server.py tests
uv run ruff check mealie_server.py tests
uv run python -m unittest discover -s tests -p 'test_*.py' -v
uv run pip-audit --skip-editable

The regression suite mocks network and filesystem boundaries. It covers mutation gating, confirmation, sensitive-path blocking, OpenAPI validation, SSRF/local-file confinement, multipart limits, Mealie v3 request shapes, ingredient preservation, and credential-safe status output.

Known boundaries

• This is a stdio MCP server, not a remotely exposed HTTP service.
• Mealie streaming/SSE import operations are intentionally unsupported.
• Generic operations follow the live Mealie OpenAPI, but dedicated helper tools may need adaptation after breaking Mealie API changes.
• Raw API paths are fail-closed unless they match a live OpenAPI operation; sensitive path prefixes and OpenAPI tags remain denied.
• Public-address validation reduces SSRF risk but cannot enforce the network behavior of Mealie itself. When enabling URL imports or remote sources, also restrict container/host egress and DNS at the deployment layer.
• Chefkoch integration is optional functionality supplied through the get-chefkoch dependency.
• OCR quality depends on the local Tesseract installation and source image quality.

License

MIT — see LICENSE.