Mealie MCP Server

Fork of amercat37/mealie-mcp-server (itself based on rldiao/mealie-mcp-server). This fork adds recipe import from URLs, page HTML and social posts (import_recipe_from_url, import_recipe_from_html, set_recipe_image, the import_recipe prompt) and Proxmox LXC deployment without Docker (see deploy/README.md). Build notes: PLAN.md.

A Model Context Protocol (MCP) server for Mealie that lets AI assistants like Claude and ChatGPT read your recipe database, manage shopping lists, create and edit meal plans, and guide you through cooking — served over HTTP and secured with OAuth 2.0.

✨ Features

🔐 Single-User OAuth 2.0 Authentication (optional)

• Authentik integration: Validates bearer tokens via OIDC discovery + JWKS, with RS256 signature pinning and automatic signing-key rotation

• Audience-scoped: rejects tokens minted for other apps that share your Authentik issuer — AUTHENTIK_AUDIENCE is required when auth is enabled

• Opt-in: runs unauthenticated when AUTHENTIK_ISSUER is not set

• Docker-friendly: supports internal JWKS fetching via AUTHENTIK_JWKS_URI + AUTHENTIK_HOST

🍽️ Recipe Management

• Advanced Search: Filter by text, categories, tags, and tools with AND/OR logic

• Dual Detail Levels: Concise summary for planning, full details for cooking

• Create Recipes: Build fully structured recipes from scratch — categories, tags, tools, and ingredients resolved from existing library conventions automatically

• Duplicate Recipes: Clone any recipe under a new name for variations or scaling

• Metadata Tracking: Mark recipes as made, track last made dates

• Comments: Read and write cooking notes per recipe

• Timeline: View chronological cooking activity across all recipes

• Sharing: Create and list public share links for any recipe — links anyone can open without a login (needs MEALIE_PUBLIC_URL)

• Recipe links: get_recipe_detailed includes the recipe's page in Mealie (open, edit, print or save as PDF) when MEALIE_PUBLIC_URL is set

🛒 Shopping Lists

• List Management: Create, rename, and delete shopping lists

• Label Ordering: Reorder a list's sections by label name to match a store's layout

• Item Operations: Add, update, check off, and remove items

• Bulk Operations: Create, update, or delete multiple items at once

• Recipe Integration: Add one or many recipes' ingredients to a list at once

🏷️ Organization

• Categories: Browse recipe categories (Breakfast, Dinner, etc.); find unused categories

• Tags: Browse and filter by recipe tags; find unused tags

• Foods: Search the ingredient food library; add new foods; merge duplicates

• Tools: List cooking equipment tagged on recipes

• Units: List units of measurement used in ingredients

• Labels: List shopping list labels (grocery store sections)

• Cookbooks: Browse curated recipe collections (My Recipes, The Autoimmune Solution)

📅 Meal Planning

• View & Create: See all meal plans, today's menu, and add new entries

• Edit & Delete: Update or remove individual meal plan entries

• Bulk Creation: Add multiple meals at once — all entries are checked first, and the created ids come back

• Whole-Week Entries: Plan a meal for "sometime this week" (Mealie v3.30+), aligned to the household's first day of week

💬 Prompts

Six built-in conversation starters that pre-configure the assistant for specific tasks:

• recipe_builder: Guided recipe creation — fetches similar recipes to match your conventions, resolves foods/tags/categories from your existing library, defaults to My Recipes cookbook

• weekly_meal_plan: Guided meal planning with tag filtering, sandwich rules, and leftover logic

• shopping_trip: Consolidated shopping list from your meal plan, grouped by store section with cost estimates

• cooking_session: Full recipe details, equipment, and cooking notes staged before you start cooking

• weekly_review: Summary of what you've cooked and eaten, answers "what did I have last Wednesday?"

• nutrition_summary: Caloric and macro breakdown from your meal plan's nutrition data

Related MCP server: Mealie MCP Server

🚀 Installation

Prerequisites

• Docker and Docker Compose

• A running Mealie instance, v3.30.0 or later, with an API key (recipe times use Mealie's structured durations from v3.29 and whole-week meal plans from v3.30; an older Mealie silently ignores them)

• An Authentik instance with a provider, app, and user configured (only required if using OAuth)

Step 1 — Clone the repository

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

Step 2 — Configure environment

cp .env.template .env
# Edit .env with your values

Set the variables in .env. The AUTHENTIK_JWKS_URI + AUTHENTIK_HOST pair is only needed if Authentik and this server share a Docker network — it lets the server fetch signing keys from the internal address rather than going through the public domain. Set the optional MEALIE_PUBLIC_URL (the address you open Mealie at in a browser) to get working share links and recipe page links; without it those tools say no link can be built.

Step 3 — Start the server

docker compose up -d

The server listens on port 8000 at /mcp. Configure your MCP client to connect to http://your-host:8000/mcp (or via a reverse proxy with TLS).

OAuth / Authentik Setup (optional)

Authentication is opt-in. If AUTHENTIK_ISSUER is not set, the server starts without any authentication — useful for local testing.

When enabled, the server validates OAuth 2.0 bearer tokens issued by Authentik. Your MCP client redirects you to your Authentik login page, you log in, and Authentik issues a token. The MCP server checks that token on every request. Your Mealie API key never leaves the server.

Step 1 — Create a Provider in Authentik

In the Authentik admin UI go to Applications → Providers → Create → OAuth2/OpenID Provider.

Callback URI examples:

strict: https://claude.ai/api/mcp/auth_callback
strict: https://chatgpt.com/connector/oauth/<your-connector-id>

Save the provider. On the detail page, note the OpenID Configuration Issuer URL — it looks like:

https://auth.your-domain.com/application/o/mealie-mcp-server/

This is your AUTHENTIK_ISSUER value. On the same provider detail page, note the Client ID — this is your AUTHENTIK_AUDIENCE value.

⚠️ AUTHENTIK_AUDIENCE is required when authentication is enabled. The server verifies that each token's aud claim contains this Client ID, so a token minted for a different Authentik application can't be replayed against this server. If AUTHENTIK_ISSUER is set but AUTHENTIK_AUDIENCE is not, the server will refuse to start.

Step 2 — Create an Application in Authentik

Go to Applications → Applications → Create.

Save.

Step 3 — Create and Assign a User

By default, all Authentik users can access the application. To restrict access, open the application → Policy / Group / User Bindings tab → Bind existing policy/group/user and add the specific users or groups you want to allow.

Project Structure

mealie-mcp-server/
├── src/
│   ├── mealie/              # API client mixins
│   │   ├── client.py        # Base HTTP client
│   │   ├── recipe.py        # Recipe operations
│   │   ├── shopping_list.py # Shopping list operations
│   │   ├── categories.py    # Category operations
│   │   ├── tags.py          # Tag operations
│   │   ├── mealplan.py      # Meal plan operations
│   │   ├── foods.py         # Food operations
│   │   ├── cookbooks.py     # Cookbook operations
│   │   ├── organizers.py    # Tools, units, and labels
│   │   └── __init__.py      # MealieFetcher aggregator
│   ├── tools/               # MCP tool definitions
│   │   ├── recipe_tools.py
│   │   ├── shopping_list_tools.py
│   │   ├── categories_tools.py
│   │   ├── tags_tools.py
│   │   ├── mealplan_tools.py
│   │   ├── foods_tools.py
│   │   ├── cookbooks_tools.py
│   │   ├── organizers_tools.py
│   │   └── __init__.py
│   ├── models/              # Pydantic models
│   │   ├── mealplan.py
│   │   └── recipe.py
│   ├── auth.py              # OAuth/JWT verification (Authentik)
│   ├── server.py            # MCP server entry point
│   ├── prompts.py           # Server prompts
│   └── utils.py             # Shared utilities
├── .github/
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── ISSUE_TEMPLATE/
│       ├── bug_report.md
│       └── feature_request.md
├── tests/
│   ├── test_fetcher.py
│   ├── test_mcp_server.py
│   ├── docker-compose.yml
│   ├── .env.testing.template
│   └── README.md
├── Dockerfile
├── docker-compose.yml
├── .env.template
├── CHANGELOG.md
└── README.md

📚 Important Notes

Filtering by Tags/Categories

When filtering recipes, you must use slugs or UUIDs, not display names:

✅ Correct:

"Get recipes with tags=['quick-meals', 'healthy']"

❌ Incorrect:

"Get recipes with tags=['Quick Meals', 'Healthy']"

Use get_tags() or get_categories() first to find the correct slugs.

Recipe Detail Levels

Two tools fetch recipe data — use the right one for the task:

Field Preservation

When updating shopping list items, the server automatically preserves all existing fields. You only need to specify the fields you want to change:

# Only updates 'checked' field, preserves note, quantity, etc.
update_shopping_list_item(item_id="...", checked=True)

🔄 Changelog

See CHANGELOG.md for a detailed list of changes and version history.

🔮 Future Enhancements

• Multi-user support (step 1): Store each user's Mealie API key as an attribute in Authentik and include it in the JWT via a property mapping — each user brings their own key, no admin involvement

• Multi-user support (step 2): Configure Mealie as an OAuth provider backed by Authentik and implement OAuth token exchange (RFC 8693) — eliminating API keys entirely

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

For issues and questions:

• Check the CHANGELOG.md for recent updates

• Review the Mealie API documentation

• Open an issue on GitHub

🔗 Related Links

• Mealie Documentation

• MCP Protocol Specification

• Authentik