Base de Conhecimento

MongoDB no n8n: consulte e grave documentos

  • mongodb, n8n, banco de dados, automação, workflow
  • Usuários acharam útil: 0

Proteja o banco, crie a credencial MongoDB, teste um Find e consulte com Query Parameters. Grave documentos com Insert e Update, com ou sem Upsert, e saiba o que cuidar no Delete e no Aggregate.

Por Redação Eleven Host · @robson.direitodigital · 17 de novembro de 2026 · 8 min de leitura

Arte da Eleven Host: janela de terminal com o título: MongoDB no n8n: consulte e grave documentos

Capa da Redação Eleven Host para o tutorial: MongoDB no n8n: consulte e grave documentos Arte: Eleven Host

Usar mongodb no n8n é ligar o fluxo a um banco de documentos: o nó MongoDB consulta, insere, atualiza e apaga documentos de uma coleção, o que serve para guardar cadastros, pedidos e registros que outros nós produzem.

Quando o dado vem de fora do fluxo, como um formulário ou um webhook, o editor do nó MongoDB manda usar Query Parameters ($1, $2) em vez de colocar uma expressão com chaves duplas dentro da query.

Atualizado em 17/11/2026. Em 17/11/2026, a versão estável do n8n na página de lançamentos do projeto é a 2.48.4, publicada em 13/11/2026.

O que o nó MongoDB faz

O MongoDB guarda dados em documentos, que são registros em formato parecido com JSON, e agrupa os documentos em coleções. Quem vem de planilha pode pensar na coleção como a aba e no documento como a linha.

Segundo a documentação do n8n, o nó MongoDB automatiza trabalho no MongoDB e integra o banco a outros aplicativos, usando o driver oficial para Node. Não existe MongoDB Trigger: o fluxo começa por outro nó, como agendamento, webhook ou gatilho manual.

O campo Resource tem duas opções: Document, o padrão, e Search Index. Em Document, o campo Operation traz Find como padrão, além de Aggregate, Delete, Find And Replace, Find And Update, Insert e Update. O campo Collection é obrigatório em todas.

Para que serve num fluxo

Alguns usos em empresas pequenas: gravar os contatos que chegam por um formulário, consultar se um cliente já existe antes de criar outro registro e listar os pedidos acima de certo valor para um relatório diário. Para guardar chaves simples, o Redis no n8n: cache e filas nos seus fluxos é outra opção. Para dados em tabelas, há o artigo Supabase no n8n: leia e grave dados nas tabelas.

Quem ainda não tem servidor encontra a escolha explicada no guia O que é servidor VPS.

Planos mensais de VPS, do Bronze ao Titanium, estão na loja. VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver as VPS

Passo 1: deixar o MongoDB protegido antes de conectar

O checklist de segurança do MongoDB pede controle de acesso ligado, com um mecanismo de autenticação, e menor privilégio: primeiro um administrador de usuários, depois um usuário para cada pessoa ou aplicação. Para o n8n, recomendamos um usuário só dele, com o papel readWrite apenas no banco usado pelos fluxos.

Sobre a rede, a documentação do MongoDB diz que ele escuta só no localhost por padrão, e que 0.0.0.0 ou net.bindIpAll abrem todas as interfaces; com mais de uma interface, ligue-o à rede privada. A porta padrão é a 27017, e a documentação pede rede confiável, com firewall liberando só clientes confiáveis, para evitar exposição à internet sem querer. Por isso, recomendamos não publicar a porta 27017 para fora: com Docker, deixe o MongoDB só na rede interna, junto com o n8n.

Se o n8n rodar em Docker, localhost dentro do contêiner é o próprio contêiner: com o MongoDB em outro contêiner, o Host da credencial é o nome do serviço na mesma rede Docker.

Passo 2: criar a credencial MongoDB

No n8n, crie a credencial MongoDB. O campo Configuration Type tem duas opções, Connection String e Values, e o padrão é Values.

  • Values: preencha Host (padrão localhost), User, Password e Port (padrão 27017);
  • Connection String: cole a string completa. Se ela for preenchida, o n8n usa a string e ignora os valores de usuário e senha. Um exemplo de formato: mongodb://usuario:senha@host:27017/?authSource=banco, em que authSource é o banco onde o usuário foi criado. Confira o formato no seu servidor;
  • Database: o nome do banco, que deve ser informado nos dois modos, mesmo com string de conexão.

Para senha com caracteres especiais (@, :, /) ou para Atlas, recomendamos a Connection String. No Atlas, a documentação do n8n manda adicionar o IP do n8n na IP Access List, em Network Access.

A opção Use TLS vem desligada. Ligue só se o servidor estiver configurado para TLS e você tiver o certificado. Ao ligar, aparecem campos para CA Certificate, certificado e chave do cliente e Passphrase. A credencial não tem opção para ignorar a verificação do certificado.

Passo 3: testar com um Find

Crie um workflow com gatilho manual e adicione o nó MongoDB. Escolha a credencial, deixe Operation em Find e informe a Collection. Em Query (JSON Format), deixe {}, que casa com todos os documentos. Em Options, adicione Limit com 5 e execute o nó. Cada documento retornado vira um item na saída.

Consultar com filtro e Query Parameters

O Find recebe o filtro em JSON no campo Query (JSON Format). Os valores variáveis ficam fora do JSON, no campo Query Parameters, que é uma lista também em JSON. O texto $1 entra no lugar do primeiro item da lista, $2 no do segundo, e assim por diante.

Um exemplo de busca por e-mail: em Query, { "email": "$1" }; em Query Parameters, ["{{ $json.email }}"]. A expressão com chaves duplas fica no campo de parâmetros, onde o n8n a resolve como valor, e a query continua sendo só o filtro.

Um exemplo de busca por faixa: em Query, { "total": { "$gte": "$1" } }; em Query Parameters, [100]. O operador $gte fica escrito direto na query.

Um exemplo de busca por identificador: em Query, { "_id": "$1" }, com o texto do ObjectId em Query Parameters; o n8n converte esse _id para ObjectId.

Se um parâmetro estiver errado, o nó retorna erro: JSON inválido, placeholder sem valor correspondente ou parâmetro que não foi usado. Um exemplo é um $2 na query com um só item na lista.

Resumo dos campos por operação

  • Insert: Fields;
  • Update, Find And Update e Find And Replace: Update Key, Fields e Upsert;
  • Delete e Aggregate: Query e Query Parameters.

Em Insert, Update, Find And Update e Find And Replace, as Options trazem Date Fields e Use Dot Notation.

Gravar documentos: Insert e Update com Upsert

No Insert, o campo Fields diz quais campos do item entram no documento. Um exemplo: os itens chegam com nome, email e criado_em, e em Fields vai nome,email,criado_em. A saída acrescenta o campo id com o identificador gerado pelo banco.

Para gravar uma data como tipo Date do MongoDB, adicione Date Fields em Options e informe o campo, como criado_em. Sem isso, a data vai como texto.

No Update, o nó procura o documento pela Update Key, que é obrigatória e tem id como padrão. Um exemplo: Update Key email, Fields status e Upsert ligado. O nó atualiza o documento com aquele e-mail e, se nenhum casar, cria um novo. O Upsert vem desligado: sem ele, o documento que não existe não é criado.

Dois cuidados com a Update Key. Itens sem o campo da chave são pulados sem erro, então confira que cada item traz o campo. E recomendamos que a chave seja fixa no nó, e não venha de entrada que o usuário controla, como o corpo de um webhook. A Update Key não pode ficar vazia nem começar com $, e o valor do campo não pode ser objeto, lista ou nulo. Com _id, o valor precisa ser um texto de ObjectId válido.

A saída do Update é o próprio item enviado, e não um resultado do banco: ela não informa quantos documentos foram alterados. Find And Replace troca o documento inteiro, enquanto Update altera só os campos de Fields.

Com Use Dot Notation ligado, o nó lê campos aninhados, como endereco.cidade.

Delete e Aggregate com cuidado

O Delete apaga os documentos que casam com a query, e não só um. Como o padrão do campo é {}, que casa com todos, uma query vazia pode esvaziar a coleção. Teste a mesma query num Find antes de apagar.

No Aggregate, a pipeline é uma lista JSON de etapas. Um exemplo: [ { "$match": { "status": "$1" } }, { "$group": { "_id": "$cidade", "total": { "$sum": 1 } } } ], com ["ativo"] em Query Parameters, conta documentos ativos por cidade. Os parâmetros inserem só valores literais, e a referência $cidade fica direto na pipeline, como a dica do editor indica.

Nós de IA com MongoDB

Dois nós de IA do n8n usam o MongoDB: o MongoDB Chat Memory, que guarda o histórico de conversa de um agente, e o MongoDB Atlas Vector Store, que depende de um índice de busca vetorial criado na coleção no Atlas.

Problemas comuns

  • Conexão que não abre: confira Host, Port e Database. Em Docker, com o MongoDB em outro contêiner, o Host é o nome do serviço; no Atlas, confira a IP Access List;
  • Update sem efeito: veja se o item traz o campo da Update Key;
  • Fluxo que para num item: com Continue On Fail ligado, o item com erro vira um objeto com o campo error, e o fluxo segue.

Recomendamos manter o n8n atualizado.

Próximos passos

Com a conexão testada, vale começar por uma coleção de teste antes de ligar o fluxo aos dados reais.

Preço e plano de VPS se comparam na loja, em reais por mês. VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Conhecer as VPS

Perguntas frequentes

Existe um MongoDB Trigger no n8n?

Não. O n8n tem o nó MongoDB com operações como Find, Insert e Update, e não há um gatilho próprio para ele. O fluxo começa por outro nó, como agendamento ou webhook.

O Update informa quantos documentos alterou?

Não. A saída é o próprio item enviado ao nó. Para conferir, consulte o documento com um Find.

Posso colocar uma expressão com chaves duplas dentro da query?

O editor do nó recomenda usar Query Parameters para valores variáveis. Dados de formulário, webhook ou agente de IA ficam melhor no campo de parâmetros.

Esta resposta lhe foi útil?

Artigos Relacionados