Mealie MCP Server
A Model Context Protocol (MCP) server that enables AI assistants to interact with Mealie for recipe management, meal planning, and shopping lists.
Features
Tools (31 total)
Recipes
mealie_recipes_search- Search recipes by name, tags, or categoriesmealie_recipes_get- Get full recipe details including ingredients and instructionsmealie_recipes_list- List all recipes with paginationmealie_recipes_create- Create a new recipemealie_recipes_create_from_url- Import recipe by scraping a URLmealie_recipes_update- Update an existing recipemealie_recipes_update_structured_ingredients- Update recipe with structured ingredients from parsermealie_recipes_delete- Delete a recipe
Meal Planning
mealie_mealplans_list- List meal plans for a date rangemealie_mealplans_today- Get today's mealsmealie_mealplans_get- Get specific meal plan entrymealie_mealplans_get_date- Get meals for a specific datemealie_mealplans_create- Create meal plan entrymealie_mealplans_update- Update meal plan entrymealie_mealplans_delete- Delete meal plan entrymealie_mealplans_random- Get random meal suggestion
Shopping Lists
mealie_shopping_lists_list- List all shopping listsmealie_shopping_lists_get- Get shopping list with itemsmealie_shopping_lists_create- Create new shopping listmealie_shopping_lists_delete- Delete shopping listmealie_shopping_items_add- Add item to listmealie_shopping_items_add_bulk- Add multiple items at oncemealie_shopping_items_check- Mark item checked/uncheckedmealie_shopping_items_delete- Remove item from listmealie_shopping_add_recipe- Add recipe ingredients to listmealie_shopping_generate_from_mealplan- Generate shopping list from meal planmealie_shopping_clear_checked- Clear all checked items
Ingredient Parsing
mealie_parser_ingredient- Parse single ingredient string to structured formatmealie_parser_ingredients_batch- Parse multiple ingredient strings at once
Resources
recipes://list- Browse all recipesrecipes://{slug}- View specific recipemealplans://current- Current week's meal planmealplans://today- Today's mealsmealplans://{date}- Specific date's mealsshopping://lists- All shopping listsshopping://{list_id}- Specific shopping list
Prerequisites
- Docker (or Podman)
- A running Mealie instance
- Mealie API token
Quick Start
1. Get the Docker Image
Option A: Pull from GitHub Container Registry (recommended)
docker pull ghcr.io/mdlopresti/mealie-mcp:latest
Option B: Build from source
git clone https://github.com/mdlopresti/mealie-mcp.git
cd mealie-mcp
docker build -t mealie-mcp:latest .
2. Get Your API Token
- Log into your Mealie instance
- Go to User Settings (click your name in sidebar)
- Navigate to API Tokens
- Create a new token (e.g., "MCP Server")
- Copy the token immediately (it won't be shown again)
3. Configure Claude Code
Add to .mcp.json in your project root:
{
"mcpServers": {
"mealie": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MEALIE_URL=https://your-mealie-instance.com",
"-e", "MEALIE_API_TOKEN=your-api-token-here",
"ghcr.io/mdlopresti/mealie-mcp:latest"
]
}
}
}
Then add mealie to your ~/.claude/settings.json:
{
"allowedMcpServers": [
{ "serverName": "mealie" }
]
}
4. Test the Connection
Restart Claude Code and try:
Can you search for recipes in Mealie?
Usage Examples
Clearing Optional Fields
To clear an optional field (remove its value), pass the special sentinel value "__CLEAR__":
# Remove recipe association from a meal plan entry
mealie_mealplans_update(
mealplan_id="abc-123",
recipe_id="__CLEAR__"
)
# Clear the title from an entry
mealie_mealplans_update(
mealplan_id="abc-123",
title="__CLEAR__"
)
# Clear the text/notes from an entry
mealie_mealplans_update(
mealplan_id="abc-123",
text="__CLEAR__"
)
# Clear multiple fields at once
mealie_mealplans_update(
mealplan_id="abc-123",
recipe_id="__CLEAR__",
title="__CLEAR__",
text="__CLEAR__"
)
To leave a field unchanged, simply omit it from the call:
# Update only the date, preserving all other fields
mealie_mealplans_update(
mealplan_id="abc-123",
meal_date="2025-12-25"
)
Development
Local Development (without Docker)
# Create virtual environment
python -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Set environment variables
export MEALIE_URL=https://your-mealie-instance.com
export MEALIE_API_TOKEN=your-api-token
# Run server
python -m src.server
Running Tests
Unit/Integration Tests (mock API, always run):
# Run all tests except E2E
pytest -m "not e2e"
# Run all tests with coverage
pytest --cov=src --cov-report=term-missing
End-to-End Tests (optional):
E2E tests validate against a real Mealie instance. Two modes are supported:
Docker E2E Tests (recommended - isolated environment):
# Install test dependencies
pip install -r requirements-dev.txt
# Run Docker E2E tests
pytest tests/e2e/test_docker_e2e.py -v
# These tests:
# - Start a containerized Mealie instance automatically
# - Run tests in isolated environment
# - Clean up containers and data after tests
# - Require Docker/Podman to be running
Live Instance E2E Tests (test against existing server):
# Set required environment variables
export MEALIE_E2E_URL="https://your-mealie-instance.com"
export MEALIE_E2E_TOKEN="your-test-api-token"
# Run E2E tests against live instance
pytest -m e2e
# These tests are skipped if environment variables are not set
See tests/e2e/README.md for detailed E2E testing documentation.
Note: Live instance E2E tests create and delete test resources. Use a test/development instance, not production!
Project Structure
mealie-mcp/
├── Dockerfile # Container definition
├── requirements.txt # Python dependencies
├── build.sh # Build helper script
└── src/
├── server.py # MCP server entry point
├── client.py # Mealie API client
├── tools/ # MCP tool implementations
│ ├── recipes.py
│ ├── mealplans.py
│ ├── shopping.py
│ └── parser.py
└── resources/ # MCP resource implementations
├── recipes.py
├── mealplans.py
└── shopping.py
Security
- Never commit API tokens - Use environment variables
- The API token has full access to your Mealie account
- Consider creating a dedicated Mealie user for the MCP server
Requirements
- Python 3.12+
- Mealie v1.0+ (tested with v3.6.1)
License
MIT
Contributing
Contributions welcome! Please open an issue or PR.
Related
- Mealie - Self-hosted recipe manager
- Model Context Protocol - MCP specification
- FastMCP - Python MCP framework