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>

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

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.