dbt MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Primeira parte — MCP oficial da dbt Labs
Funciona em dbt Core (local) + dbt Cloud/Platform (hospedado)
Integração da Semantic Layer: list_metrics, query_metrics, get_dimensions
Lineage + saúde do modelo + desempenho prontos para usar

Demo ao vivo

Como fica na prática

dbt.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "dbt",
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "dbt": {
      "command": {
        "path": "uvx",
        "args": [
          "dbt-mcp"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add dbt -- uvx dbt-mcp

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: dbt

Diagnosticar por que um modelo dbt está falhando e propor uma correção

👤 Engenheiros de Analytics ⏱ ~15 min intermediate

Quando usar: Uma execução dbt agendada falhou. Você precisa saber o que quebrou e por quê, sem abrir 5 UIs.

Pré-requisitos

Conta dbt Cloud + token de serviço — dbt Cloud → Profile → API Tokens
Clone local do projeto dbt (se usar ferramentas CLI) — git clone seu repositório dbt

Fluxo

Encontre a execução com falha

Liste minhas 10 últimas execuções de job no dbt Cloud. Mostre quais falharam e seus resumos de erro.✓ Copiado

→ IDs de execução com falha com timestamps
Mergulhe no modelo com falha

Para a execução com falha, qual modelo falhou primeiro? Obtenha seus detalhes (SQL, descrição) e seu lineage upstream.✓ Copiado

→ Modelo com falha + cadeia de dependências
Proponha correção

Execute o modelo localmente com dbt compile. Inspecione o SQL compilado para encontrar o erro. Proponha a edição mínima para corrigir.✓ Copiado

→ Correção SQL concreta com justificativa

Resultado: Uma correção validada para um modelo quebrado em menos de 15 minutos.

Armadilhas

Falhas de execução em nuvem podem ser ambientais (conexão/credenciais), não código — Antes de editar SQL, verifique se o mesmo modelo é executado localmente via ferramenta run — se sim, é infra não código

Combine com: sentry · linear

Responder a uma pergunta de negócio usando a Semantic Layer do dbt

👤 Engenheiros de Analytics que habilitam self-serve ⏱ ~10 min beginner

Quando usar: Um stakeholder pergunta 'qual foi a MRR por plano no mês passado?' — você tem métricas definidas em dbt SL.

Pré-requisitos

Semantic Layer habilitada em seu projeto dbt Platform — dbt Cloud → Account Settings → Semantic Layer

Fluxo

Encontre a métrica

Liste as métricas disponíveis em nossa SL. Estou procurando por MRR ou monthly_revenue.✓ Copiado

→ Métrica correspondente encontrada
Verifique dimensões

Por quais dimensões a métrica MRR é consultável? Quero filtrar/agrupar por plano e mês.✓ Copiado

→ Lista de dimensão válida
Consulte e interprete

Consulte MRR do mês passado, agrupado por plano. Formate o resultado como uma tabela e comente sobre os maiores contribuidores.✓ Copiado

→ Tabela + breve análise

Resultado: O stakeholder obtém uma resposta confiável e governada em 2 minutos; ninguém escreveu SQL ad-hoc.

Armadilhas

Consultar por uma dimensão não suportada retorna vazio sem erro claro — Sempre chame get_dimensions na métrica primeiro; não assuma

Combine com: notion

Verifique o impacto antes de editar um modelo central

👤 Engenheiros de Analytics prestes a tocar em um modelo fundamental ⏱ ~20 min intermediate

Quando usar: Você está prestes a mudar dim_customers. Você precisa saber cada consumidor downstream primeiro.

Fluxo

Obtenha lineage

Obtenha o lineage downstream para dim_customers. Inclua modelos, exposições e qualquer métrica.✓ Copiado

→ Gráfico downstream completo
Quantifique o impacto

Para cada modelo downstream, obtenha seu model_performance e model_health — quais são críticos (usados por exposições, executados diariamente)?✓ Copiado

→ Lista de prioridade do que quebrará se você cometer um erro
Planeje a mudança

Escreva um plano de mudança: quais testes adicionar, quais proprietários downstream notificar (verifique exposições) e o que monitorar após a implantação.✓ Copiado

→ Plano de implementação

Resultado: Mudanças em modelos compartilhados são implantadas com consciência, não com surpresas de raio de explosão.

Armadilhas

Exposições só existem se você as mantiver — downstream silencioso em ferramentas de BI não é rastreado — Combine com a API da sua ferramenta de BI (Looker, Tableau) para encontrar consumidores reais; dbt só sabe o que lhe é dito

Criar modelos de staging a partir de fontes brutas

👤 Engenheiros de Analytics integrando uma nova fonte ⏱ ~30 min intermediate

Quando usar: Novos dados Fivetran/fonte chegam. Você precisa de um modelo stg_* + yml para cada tabela.

Pré-requisitos

Entradas sources.yml para os novos dados — Defina as fontes primeiro; o agente gera staging a partir daí

Fluxo

Gere bloco de origem

Use generate_source para banco de dados 'raw', schema 'stripe'. Escreva a saída em models/staging/stripe/_sources.yml.✓ Copiado

→ Yml de origem preenchido com todas as tabelas
Crie modelos de staging

Para cada tabela de origem, chame generate_staging_model. Escreva cada uma em models/staging/stripe/stg_stripe__<table>.sql.✓ Copiado

→ Um .sql por tabela de origem
Adicione docs + testes

Para cada novo modelo de staging, chame generate_model_yaml. Adicione testes not_null em chaves primárias. Faça commit.✓ Copiado

→ Camada de staging limpa e testada

Resultado: Uma camada de staging completa em minutos; sem desvio de cópia-cola.

Armadilhas

Modelos gerados usam SELECT * que então extrai colunas PII — Após a geração, liste explicitamente as colunas e exclua/hash aquelas sensíveis antes de mesclar

Combine com: git

Combinações

Combine com outros MCPs para 10× de alavancagem

dbt + sentry

Quando uma falha de modelo dbt quebra recursos downstream, correlacione com picos de erro do Sentry

Encontre execuções dbt com falha nas últimas 24h. Para cada uma, verifique o Sentry para picos de erro em serviços que dependem das tabelas desses modelos.✓ Copiado

dbt + linear

Arquivo de bugs do Linear para falhas recorrentes de testes dbt

Liste testes dbt que falharam mais de 3 vezes na semana passada. Para cada um, crie um bug do Linear no time de Analytics com os detalhes do teste.✓ Copiado

dbt + notion

Auto-documentar métricas em um glossário Notion

Para cada métrica em nossa Semantic Layer, crie ou atualize uma página Notion no banco de dados Metrics Glossary com nome, descrição e proprietário.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_metrics / get_dimensions / get_entities / query_metrics	nome da métrica, dimensões, filtros	Perguntas de negócio sobre métricas	Consultas de SL cobráveis por plano dbt Cloud
execute_sql / text_to_sql	SQL ou linguagem natural	Exploração de SQL ad hoc com contexto dbt	Créditos de warehouse
get_all_models / get_model_details / get_lineage	identificadores de modelo	Descoberta + análise de impacto	grátis
get_model_health / get_model_performance	id do modelo	Verificações no estilo SRE na plataforma de dados	grátis
build / run / test / compile / parse / show / docs / list	dbt CLI args	Uso local de dbt Core	warehouse compute para run/test/build
list_jobs / trigger_job_run / get_job_details / cancel_job_run / retry_job_run / list_job_runs	job/run IDs	Operações dbt Cloud	1 Admin API call
generate_source / generate_staging_model / generate_model_yaml	referências de origem/modelo	Criando modelos novos	grátis
get_exposures / get_exposure_details	nome da exposição	Encontre consumidores downstream documentados como exposições	grátis

Custo e limites

O que custa rodar

Cota de API: dbt Cloud Admin API: depende do plano. Semantic Layer: limites por plano.
Tokens por chamada: Gráficos de lineage + listas de modelo podem ser grandes — pagine
Monetário: MCP é grátis; dbt Core é grátis; dbt Cloud/Platform é pago. Consultas de warehouse cobradas pelo seu warehouse.
Dica: Use ferramentas de descoberta (get_model_details, get_lineage) livremente — são metadados. Tenha cuidado com execute_sql / query_metrics que atingem o warehouse.

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Token de serviço dbt Cloud em variável de ambiente; Core usa seu profiles.yml

Saída de dados: dbt Cloud (cloud.getdbt.com) para ferramentas em nuvem; seu warehouse para ferramentas SQL

Solução de problemas

Erros comuns e correções

401 em chamadas de Admin API

Token de serviço expirado ou conta necessária ausente. Regenere em dbt Cloud → Account Settings → Service Tokens.

Ferramentas Semantic Layer retornam 'not configured'

SL é um recurso pago e deve ser ativado por projeto. Verifique dbt Cloud → Project Settings → Semantic Layer.

Ferramentas CLI (run/build) falham com 'No profile'

Defina DBT_PROFILES_DIR para um diretório contendo profiles.yml ou execute da raiz do projeto com um profiles.yml local.

Verificar: dbt debug

get_lineage retorna vazio

Manifesto está obsoleto. Execute parse primeiro para regenerar manifest.json.

Alternativas

dbt vs. outros

Alternativa	Quando usar	Troca
SQLMesh MCP	Você usa SQLMesh em vez de dbt	Paradigma de transformação diferente; não é uma troca direta
Direct warehouse MCPs (Snowflake, BigQuery)	Você só precisa de SQL bruto, não de metadados dbt	Perca consciência de modelo/lineage/teste

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills