mealie-mcp
A Model Context Protocol server that exposes Mealie — a self-hosted recipe manager — as a set of LLM-callable tools. It lets Claude Desktop / Claude Code (or any MCP client) search recipes, fetch details, manage the meal plan, and edit shopping lists on your own Mealie instance.
Tools
| Tool | Purpose |
|---|---|
search_recipes(query?, tags?, limit?) | Search recipes; returns slug, name, description, tags, categories |
get_recipe(slug) | Full recipe JSON for a slug |
list_meal_plan(start_date, end_date) | Meal plan entries between two ISO dates |
list_shopping_lists() | IDs and names of all shopping lists |
add_shopping_list_items(list_id, items[]) | Add free-text items to a list |
create_recipe(name) | Create a blank recipe; returns generated slug |
create_meal_plan_entry(date, entry_type, recipe_slug?, title?) | Add a meal plan entry |
Requirements
- Python 3.11+
- A running Mealie instance (self-hosted; tested against Mealie v2)
- A long-lived Mealie API token (User Profile → API Tokens in the Mealie UI)
Configuration
Copy .env.example to .env and fill in the values:
cp .env.example .env
| Variable | Required | Default | Description |
|---|---|---|---|
MEALIE_URL | yes | — | Base URL of your Mealie instance (e.g. http://localhost:9011 or http://mealie:9000) |
MEALIE_API_TOKEN | yes | — | Long-lived bearer token from Mealie |
MCP_TRANSPORT | no | sse | stdio for local subprocess, sse for HTTP streaming |
MCP_HOST | no | 0.0.0.0 | Bind address for SSE mode |
MCP_PORT | no | 8000 | Bind port for SSE mode |
Install & run locally
pip install -e .
# stdio mode (for Claude Desktop):
MCP_TRANSPORT=stdio mealie-mcp
# sse/http mode (for docker-compose / remote clients):
MCP_TRANSPORT=sse MCP_PORT=8000 mealie-mcp
The SSE endpoint is served at http://<host>:<port>/sse.
Claude Desktop configuration
Edit Claude Desktop's config file (macOS:
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"mealie": {
"command": "mealie-mcp",
"env": {
"MEALIE_URL": "http://localhost:9011",
"MEALIE_API_TOKEN": "paste-your-token-here",
"MCP_TRANSPORT": "stdio"
}
}
}
}
If mealie-mcp is not on your PATH, point command at the full binary path
(e.g. /Users/you/.venvs/mealie-mcp/bin/mealie-mcp) or invoke via Python:
{
"mcpServers": {
"mealie": {
"command": "python",
"args": ["-m", "mealie_mcp"],
"env": {
"MEALIE_URL": "http://localhost:9011",
"MEALIE_API_TOKEN": "paste-your-token-here",
"MCP_TRANSPORT": "stdio"
}
}
}
}
Restart Claude Desktop after editing the config.
Docker / docker-compose
A Dockerfile is included. To run standalone:
docker build -t mealie-mcp .
docker run --rm -p 8765:8000 \
-e MEALIE_URL=http://host.docker.internal:9011 \
-e MEALIE_API_TOKEN=your-token \
mealie-mcp
To add the server to an existing Mealie stack, see
docker-compose.snippet.yml:
services:
mealie-mcp:
build:
context: ./mealie-mcp
depends_on:
- mealie
environment:
MEALIE_URL: "http://mealie:9000"
MEALIE_API_TOKEN: "${MEALIE_API_TOKEN}"
MCP_TRANSPORT: "sse"
MCP_HOST: "0.0.0.0"
MCP_PORT: "8000"
ports:
- "8765:8000"
Point your MCP client at http://<docker-host>:8765/sse.
Testing the server manually
With the server running in SSE mode, confirm it is reachable:
curl -N http://localhost:8000/sse
You should see an SSE event stream open. For stdio mode, Claude Desktop handles the handshake — there is no HTTP endpoint.
Project layout
mealie-mcp/
├── pyproject.toml
├── Dockerfile
├── docker-compose.snippet.yml
├── .env.example
├── README.md
└── src/mealie_mcp/
├── __init__.py
├── __main__.py # CLI entry point (loads .env, dispatches transport)
├── server.py # FastMCP server + tool definitions
└── client.py # Async httpx wrapper for the Mealie REST API
License
MIT