Mealie

Interaja com seu banco de receitas do Mealie para gerenciar e encontrar receitas.

Documentação

Servidor MCP Mealie

Um servidor Model Context Protocol (MCP) que conecta assistentes de IA ao seu banco de dados de receitas do Mealie por meio de clientes como o Claude Desktop.

Conteúdo

Recursos
Início Rápido
Configuração
Acesso Remoto
Docker
Exemplos de Uso
Ferramentas Disponíveis
Desenvolvimento
Notas Importantes
Suporte e Contribuição
Licença e Créditos

Recursos

Receitas: Crie, leia, atualize, importe, duplique e exclua receitas.
Busca: Filtre por texto, categorias, tags e ferramentas com lógica AND/OR.
Imagens e arquivos: Envie imagens e arquivos de receitas, ou defina imagens a partir de URLs.
Nutrição e exibição: Defina nutrição por porção e configurações de visibilidade de receitas, como showAssets e showNutrition.
Ingredientes: Resolva ingredientes em texto livre usando o vocabulário de alimentos e unidades do Mealie.
Listas de compras: Gerencie listas e itens, execute operações em lote e adicione ingredientes de receitas com escala de quantidade.
Organização: Gerencie categorias, tags, alimentos, unidades e ferramentas de receitas; encontre categorias e tags não utilizadas.
Planejamento de refeições: Veja, crie, atualize e exclua entradas de plano de refeições, crie múltiplas entradas e marque receitas como feitas hoje.

Início Rápido

Pré-requisitos

Python 3.12+
Uma instância do Mealie em execução e uma chave de API das configurações da sua conta
Gerenciador de pacotes uv

Instalação

Opção 1: Usando a CLI do SDK MCP (Recomendado)

Clone o repositório e instale o servidor no Claude Desktop com o comando mcp fornecido pelo SDK MCP Python (nenhum pacote fastmcp autônomo é necessário):

git clone https://github.com/rldiao/mealie-mcp-server.git
cd mealie-mcp-server
uv sync --locked
uv run mcp install src/server.py --with-editable . \
  --env-var MEALIE_BASE_URL=https://your-mealie-instance.com \
  --env-var MEALIE_API_KEY=your-mealie-api-key

Opção 2: Usando uvx

Adicione isto à configuração do seu cliente MCP para executar diretamente do GitHub sem clonar (no Claude Desktop, use claude_desktop_config.json):

{
  "mcpServers": {
    "mealie-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rldiao/mealie-mcp-server",
        "mealie-mcp-server"
      ],
      "env": {
        "MEALIE_BASE_URL": "https://your-mealie-instance.com",
        "MEALIE_API_KEY": "your-mealie-api-key"
      }
    }
  }
}

Reinicie o Claude Desktop para carregar o servidor.

Configuração

Defina variáveis de ambiente na configuração do seu cliente MCP ou no shell. Para um checkout local, você também pode copiar .env.template para .env e preencher os detalhes da sua instância. Nunca envie sua chave de API.

Variável	Padrão	Descrição
`MEALIE_BASE_URL`	Obrigatório	URL base do Mealie, incluindo protocolo e porta, se necessário
`MEALIE_API_KEY`	Obrigatório	Chave de API das configurações da sua conta Mealie
`MEALIE_ENABLE_AI_IMPORT`	`false`	Opte pela importação de receitas com IA; aceita `true`/`false` (sem diferenciar maiúsculas de minúsculas)
`MCP_TRANSPORT`	`stdio`	`stdio`, `streamable-http` ou legado `sse`
`MCP_HOST`	`127.0.0.1`	Endereço de bind HTTP; use `0.0.0.0` em contêineres
`MCP_PORT`	`8765`	Porta HTTP, de 1 a 65535
`LOG_LEVEL`	`INFO`	`DEBUG`, `INFO`, `WARNING`, `ERROR` ou `CRITICAL`

Acesso Remoto

O transporte stdio padrão é para clientes locais. Para atender clientes HTTP, configure suas credenciais do Mealie conforme descrito acima e execute a partir do checkout:

export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8765
uv run mealie-mcp-server

O servidor exporá seu endpoint MCP em http://<host>:<port>/mcp.

Segurança: Transportes HTTP não têm autenticação integrada. Qualquer pessoa que alcançar o endpoint pode usar as credenciais do Mealie configuradas por meio de suas ferramentas. Mantenha-o em uma interface confiável; para acesso remoto, use um proxy reverso que aplique autenticação e HTTPS.

Docker

O Dockerfile executa o servidor como um contêiner persistente.

Build

docker build -t mealie-mcp-server .

Autônomo

docker run -d \
  --name mealie-mcp \
  -e MEALIE_BASE_URL=http://your-mealie-host:9000 \
  -e MEALIE_API_KEY=your-mealie-api-key \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8765 \
  -p 127.0.0.1:8765:8765 \
  mealie-mcp-server

A porta é publicada apenas na interface loopback do host. Consulte Acesso Remoto antes de torná-la acessível remotamente.

Docker Compose

Adicione este serviço ao arquivo Compose que executa o Mealie. O exemplo assume que o serviço Mealie é nomeado mealie e ambos os serviços usam uma rede chamada mealie_net, definida nesse arquivo Compose. Defina MEALIE_API_KEY no shell ou no arquivo .env do Compose.

services:
  mealie-mcp:
    build: .
    container_name: mealie-mcp
    restart: unless-stopped
    environment:
      MEALIE_BASE_URL: http://mealie:9000
      MEALIE_API_KEY: ${MEALIE_API_KEY}
      MCP_TRANSPORT: streamable-http
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "8765"
    expose:
      - "8765"
    networks:
      - mealie_net

expose não publica uma porta do host. Conecte um proxy reverso na mesma rede para acesso remoto, seguindo as orientações de segurança HTTP.

Exemplos de Uso

"Search for chicken recipes"
"Create a new recipe for pasta carbonara"
"Mark the meatloaf recipe as made today"
"Create a shopping list for this week"
"Add all ingredients from the lasagna recipe to my shopping list"
"Plan chicken soup for lunch on Friday"

Consulte Exemplos de Uso para fluxos de trabalho detalhados e solução de problemas.

Ferramentas Disponíveis

Ferramentas de Receitas (12 operações)

get_recipes - Listar/buscar receitas com filtragem avançada
get_recipe - Obter detalhes completos da receita, ou um resumo com concise=true
create_recipe - Criar uma receita; apenas o nome é obrigatório, com ingredientes, instruções, metadados, nutrição e configurações de exibição opcionais
import_recipe_from_url - Importar uma receita de uma página da web
update_recipe - Atualizar conteúdo ou metadados, incluindo nutrição e configurações de exibição; campos omitidos são preservados, e listas vazias limpam o conteúdo
duplicate_recipe - Clonar uma receita
mark_recipe_last_made - Atualizar o carimbo de data/hora da última vez que foi feita
set_recipe_image_from_url - Definir imagem a partir de URL
upload_recipe_image_file - Enviar arquivo de imagem
upload_recipe_asset_file - Enviar documento/arquivo
update_recipe_categories_and_tags - Substituir ou limpar categorias, tags, ou ambos usando IDs
delete_recipe - Excluir receita

Ferramentas de Listas de Compras (15 operações)

get_shopping_lists - Listar todas as listas de compras
create_shopping_list - Criar nova lista
get_shopping_list - Obter lista por ID
update_shopping_list - Renomear uma lista preservando outros campos
delete_shopping_list - Excluir lista
add_recipe_to_shopping_list - Adicionar ingredientes de receita
remove_recipe_from_shopping_list - Remover ingredientes de receita
get_shopping_list_items - Listar todos os itens
get_shopping_list_item - Obter item por ID
create_shopping_list_item - Criar item único
create_shopping_list_items_bulk - Criar múltiplos itens
update_shopping_list_item - Atualizar item (preserva campos)
update_shopping_list_items_bulk - Atualizar múltiplos itens
delete_shopping_list_item - Excluir item único
delete_shopping_list_items_bulk - Excluir múltiplos itens

Ferramentas de Categorias (6 operações)

get_categories - Listar/buscar categorias
get_empty_categories - Encontrar categorias não utilizadas
create_category - Criar nova categoria
get_category - Obter por exatamente um de category_id ou category_slug
update_category - Atualizar categoria
delete_category - Excluir categoria

Ferramentas de Tags (6 operações)

get_tags - Listar/buscar tags
get_empty_tags - Encontrar tags não utilizadas
create_tag - Criar nova tag
get_tag - Obter por exatamente um de tag_id ou tag_slug
update_tag - Atualizar tag
delete_tag - Excluir tag

Ferramentas de Alimentos (5 operações)

get_foods - Listar/buscar alimentos (resolver IDs para ingredientes estruturados)
create_food - Criar um novo alimento
get_food - Obter por ID
update_food - Atualizar alimento
delete_food - Excluir alimento

Ferramentas de Unidades (5 operações)

get_units - Listar/buscar unidades
create_unit - Criar uma nova unidade
get_unit - Obter por ID
update_unit - Atualizar unidade
delete_unit - Excluir unidade

Ferramentas de Cozinha (5 operações)

get_tools - Listar/buscar ferramentas de receitas (inclui householdsWithTool)
create_tool - Criar uma nova ferramenta
get_tool - Obter por exatamente um de tool_id ou tool_slug
update_tool - Atualizar ferramenta
delete_tool - Excluir ferramenta

Ferramentas de Análise (1 operação)

parse_ingredients - Resolver uma ou mais linhas de ingredientes em uma única solicitação; sempre retorna uma lista

Ferramentas de Plano de Refeições (6 operações)

get_all_mealplans - Listar planos de refeições
create_mealplan - Criar entrada de plano de refeições
create_mealplan_bulk - Criar múltiplas entradas
update_mealplan - Atualizar uma entrada preservando campos omitidos
delete_mealplan - Excluir uma entrada
get_todays_mealplan - Obter refeições de hoje

Total: 61 ferramentas

Com MEALIE_ENABLE_AI_IMPORT=true, import_recipe_with_ai adiciona uma operação de receita opcional: 62 ferramentas no total, incluindo 13 ferramentas de receitas. Ela está ausente da descoberta e não pode ser chamada quando desabilitada.

Migração de ferramentas consolidadas (mudança significativa)

Nomes MCP redundantes foram removidos, não mantidos como aliases. Atualize a lista de ferramentas do seu cliente e atualize chamadas salvas:

Ferramenta removida	Substituição
`create_recipe_full`	`create_recipe` com os mesmos argumentos
`get_recipe_detailed`	`get_recipe` (detalhes completos por padrão)
`get_recipe_concise`	`get_recipe` com `concise=true`
`patch_recipe`	`update_recipe` com os mesmos argumentos
`set_recipe_categories`	`update_recipe_categories_and_tags` com `category_ids`
`set_recipe_tags`	`update_recipe_categories_and_tags` com `tag_ids`
`get_category_by_slug`	`get_category` com `category_slug`
`get_tag_by_slug`	`get_tag` com `tag_slug`
`get_tool_by_slug`	`get_tool` com `tool_slug`
`parse_ingredient`	`parse_ingredients(ingredients=[...])`; leia o primeiro resultado

Chamadas existentes de create_recipe e update_recipe permanecem suportadas. Atualizações de receitas agora podem combinar conteúdo e metadados, com campos omitidos ou nulos deixados inalterados. Listas de ingredientes e instruções substituem apenas os campos fornecidos. A nutrição permanece uma substituição de objeto inteiro, enquanto as configurações são mescladas.

Operações distintas permanecem separadas: gravações únicas e em lote têm contratos de resposta/falha diferentes; listas paginadas diferem de consultas individuais, consultas de organizador não utilizado e planos de refeições de hoje. Importação de receita por URL, extração de imagem por URL e envio de arquivos também realizam operações diferentes.

Importação opcional de receitas com IA

Defina MEALIE_ENABLE_AI_IMPORT=true no ambiente do seu cliente MCP, shell ou .env local. Reinicie o servidor e atualize a lista de ferramentas do cliente. Isso se aplica a stdio, SSE e Streamable HTTP. A descoberta offline do SDK permanece sem configuração e sem rede, listando apenas ferramentas padrão; o registro opcional ocorre na inicialização em tempo de execução (ou ao passar um ServerConfig habilitado explícito).

import_recipe_with_ai requer Mealie 3.23.0+ e um provedor de IA padrão configurado para o grupo do usuário da API. Aceita qualquer combinação de:

content: texto simples, HTML bruto ou JSON; também usado para correções ou notas.
url: uma URL de receita ou vídeo HTTP(S), buscada pelo Mealie e salva como fonte.
image_paths: caminhos de imagem ordenados acessíveis ao sistema de arquivos do servidor MCP, não ao computador de um chamador remoto. Múltiplas fotos se tornam uma receita; a primeira se torna sua imagem de capa.

Pelo menos uma fonte não vazia é obrigatória. As fontes são combinadas, com conteúdo colado tendo precedência quando discordam. translate_language opcional solicita tradução. create_new_organizers padrão para false: tags, categorias e ferramentas de cozinha correspondentes podem ser atribuídas, mas novas são criadas apenas quando explicitamente solicitadas.

Antes de cada importação, o servidor lê /api/groups/self para verificar aiEnabled e, para fotos, imageProviderEnabled. Capacidades ausentes/malformadas ou uma consulta falha produzem um erro explícito, não um resultado desabilitado silencioso. Detecção de vídeo e o requisito de provedor de áudio são tratados pelo Mealie. Essas verificações estabelecem configuração, não conectividade do provedor, credenciais ou cota disponível.

Esta ferramenta cria e salva imediatamente uma receita. O material de origem é processado pelos provedores de IA configurados do Mealie e pode incorrer em cobranças. Revise a receita retornada quanto à precisão. A importação tem um tempo limite de leitura de 300 segundos; outras chamadas de API mantêm seus tempos limite existentes. Nenhuma importação é tentada novamente automaticamente. Após um tempo limite ou falha de conexão, verifique o Mealie antes de tentar novamente ou trocar de ferramenta: a criação pode já ter sido bem-sucedida. Se a busca de acompanhamento falhar, o erro inclui created_slug e stage; recupere essa receita em vez de importar novamente.

Escolha a ferramenta de acordo com a tarefa:

Tarefa	Ferramenta
Página de receita comum	`import_recipe_from_url`
Texto não estruturado, fotos, vídeo, fontes combinadas, tradução ou importação explícita por IA	`import_recipe_with_ai` (opt-in)
Salvar ingredientes e instruções já compostos	`create_recipe`
Anexar uma foto a uma receita existente sem extrair conteúdo	`upload_recipe_image_file`

O opt-in controla apenas esta nova ferramenta. Ele não desativa o fallback de IA do próprio Mealie para raspagem de URL ou outros recursos existentes de IA. Consulte documentação de importação por IA do Mealie e exemplos de uso.

Desenvolvimento

Configuração

Após clonar o repositório, instale as dependências de desenvolvimento:

uv sync --locked --extra dev

Para testes manuais, configure sua instância do Mealie:

cp .env.template .env
# Edit .env with your Mealie instance details

Inicie o MCP Inspector:

uv run mcp dev src/server.py

Execute as verificações offline; elas não exigem uma instância do Mealie ou credenciais:

uv run ruff check src tests
uv run pytest -q

Estrutura do Projeto

Caminho	Finalidade
`src/mealie/`	Cliente HTTP e mixins de API
`src/tools/`	Definições e registro de ferramentas FastMCP
`src/models/`	Modelos de requisição e resposta Pydantic
`src/server.py`	Configuração, ciclo de vida e ponto de entrada
`src/prompts.py`	Prompts MCP
`tests/`	Testes offline e fixtures

As convenções do repositório estão em AGENTS.md, com orientações específicas para código-fonte e testes.

A suíte automatizada usa respostas HTTP simuladas e inclui verificações de transporte HTTP local. Ela não substitui testes de compatibilidade contra sua versão implantada do Mealie.

Notas Importantes

As chamadas abaixo usam notação estilo Python para ilustrar argumentos de ferramentas MCP; elas não são scripts Python independentes.

Filtragem por Tags e Categorias

Ao filtrar receitas, você deve usar slugs ou UUIDs, não nomes de exibição:

Use get_tags() ou get_categories() primeiro para encontrar os slugs corretos:

get_recipes(tags=["quick-meals", "healthy"])

Por exemplo, passe quick-meals, não o nome de exibição Quick Meals.

Nutrição é Substituída, Não Mesclada

O Mealie substitui todo o objeto nutrition na gravação. update_recipe segue o mesmo comportamento, então passe todos os valores que deseja manter:

# Clears every nutrition value except fat.
update_recipe(slug="...", nutrition={"fatContent": "12"})

Analisando Ingredientes em Lote

Resolver ingredientes manualmente custa uma ou duas chamadas de get_foods / get_units cada. parse_ingredients processa uma receita inteira em uma única requisição e retorna resultados que podem ser passados diretamente para create_recipe:

parse_ingredients(ingredients=["1/4 cup chopped onion", "2 large eggs"])
# -> [{"input": "1/4 cup chopped onion", "confidence": 0.99, "quantity": 0.25,
#      "unit": {"id": "...", "name": "cup"},
#      "food": {"id": "...", "name": "onion"}, "note": "chopped"}, ...]

Uma unidade ou alimento null significa que sua instância não possui uma entrada correspondente; crie uma com create_food / create_unit, ou deixe o texto na nota. Passe verbose=True para a resposta completa do Mealie, incluindo confianças por campo.

Ativos Enviados e Nutrição Podem Ser Armazenados, mas Ocultos

O objeto settings de uma receita controla o que a interface renderiza. showAssets e showNutrition controlam os cartões de ativos e nutrição, então um ativo enviado com upload_recipe_asset_file pode estar presente na resposta da API e ainda assim ser invisível na interface web. Alterne a opção com:

update_recipe(slug="...", settings={"showAssets": True})

O Mealie define as configurações de uma nova receita a partir das preferências da família (recipeShowAssets, recipeShowNutrition, ...), então os padrões diferem por instância. Verifique em vez de assumir.

Apenas as opções que você passar são alteradas. A ferramenta lê as configurações atuais da receita e envia o objeto mesclado, porque o Mealie não preserva de forma confiável opções omitidas em um PATCH de configurações.

Preservação de Campos

Ao atualizar itens de lista de compras, tanto atualizações individuais quanto em lote buscam os registros atuais e preservam campos omitidos. Você só precisa especificar os campos que deseja alterar:

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

Entradas de compras em lote aceitam nomes em snake_case, como shopping_list_id, e nomes em camelCase do Mealie, como shoppingListId. Aliases conflitantes e IDs duplicados em uma atualização em lote são rejeitados antes da gravação.

Validação e Limpeza de Planejamento de Refeições

As datas das refeições devem usar YYYY-MM-DD, e os tipos de entrada devem ser breakfast, lunch, dinner ou side. A criação exige uma receita ou um título não vazio. Planos de refeições em lote são validados por completo antes de qualquer entrada ser criada.

Campos de atualização omitidos permanecem inalterados. Para remover um link de receita existente, use update_mealplan(entry_id="...", clear_recipe=True, title="Leftovers"). Não combine clear_recipe com um recipe_id substituto.

Recuperação de Gravações Parcialmente Concluídas

A criação/população de receitas e a criação em lote de planos de refeições exigem múltiplas requisições de API e não são atômicas. Se uma requisição posterior falhar, o erro da ferramenta inclui informações de recuperação identificando o trabalho concluído. Inspecione essas informações e o estado atual do Mealie em vez de repetir cegamente toda a operação. Uma requisição com falha ou tempo esgotado pode ter sido concluída remotamente.

Suporte e Contribuição

Consulte o changelog para mudanças e notas de migração.
Revise o guia de uso e a documentação do Mealie.
Relate problemas por meio de issues no GitHub.
Para pull requests, siga o fluxo de desenvolvimento e inclua testes para mudanças de comportamento.

Licença e Créditos

Licenciado sob a Licença MIT.

Mealie - O sistema de gerenciamento de receitas
Python MCP SDK - SDK e servidor FastMCP incluído
Model Context Protocol - Documentação do protocolo
Claude Desktop