dbt CLI

Um servidor MCP que encapsula a CLI do dbt, permitindo que agentes de IA interajam com projetos dbt.

GitHub
18
Experimente este MCPPatrocinado

Documentação

DBT CLI MCP Server

Um servidor Model Context Protocol (MCP) que encapsula a ferramenta dbt CLI, permitindo que agentes de codificação de IA interajam com projetos dbt por meio de ferramentas MCP padronizadas.

Recursos

  • Executar comandos dbt por meio de ferramentas MCP
  • Suporte para todas as principais operações dbt (run, test, compile, etc.)
  • Interface de linha de comando para interação direta
  • Gerenciamento de variáveis de ambiente para projetos dbt
  • Caminho configurável para o executável dbt
  • Configuração flexível do local do arquivo profiles.yml

Instalação

Pré-requisitos

  • Python 3.10 ou superior
  • uv para gerenciamento de ambiente Python
  • dbt CLI instalado

Configuração

# Clone the repository with submodules
git clone --recurse-submodules https://github.com/yourusername/dbt-cli-mcp.git
cd dbt-cli-mcp

# If you already cloned without --recurse-submodules, initialize the submodule
# git submodule update --init

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# For development, install development dependencies
uv pip install -e ".[dev]"

Uso

Interface de Linha de Comando

O pacote fornece uma interface de linha de comando para interação direta com o dbt:

# Run dbt models
dbt-mcp run --models customers --project-dir /path/to/project

# Run dbt models with a custom profiles directory
dbt-mcp run --models customers --project-dir /path/to/project --profiles-dir /path/to/profiles

# List dbt resources
dbt-mcp ls --resource-type model --output-format json

# Run dbt tests
dbt-mcp test --project-dir /path/to/project

# Get help
dbt-mcp --help
dbt-mcp run --help

Você também pode usar o módulo diretamente:

python -m src.cli run --models customers --project-dir /path/to/project

Opções de Linha de Comando

  • --dbt-path: Caminho para o executável dbt (padrão: "dbt")
  • --env-file: Caminho para o arquivo de ambiente (padrão: ".env")
  • --log-level: Nível de registro (padrão: "INFO")
  • --profiles-dir: Caminho para o diretório que contém o arquivo profiles.yml (padrão: project-dir se não especificado)

Variáveis de Ambiente

O servidor também pode ser configurado usando variáveis de ambiente:

  • DBT_PATH: Caminho para o executável dbt
  • ENV_FILE: Caminho para o arquivo de ambiente
  • LOG_LEVEL: Nível de registro
  • DBT_PROFILES_DIR: Caminho para o diretório que contém o arquivo profiles.yml

Uso com Clientes MCP

Para usar o servidor com um cliente MCP como o Claude for Desktop, adicione-o à configuração do cliente:

{
  "mcpServers": {
    "dbt": {
      "command": "uv",
      "args": ["--directory", "/path/to/dbt-cli-mcp", "run", "src/server.py"],
      "env": {
        "DBT_PATH": "/absolute/path/to/dbt",
        "ENV_FILE": ".env"
        // You can also set DBT_PROFILES_DIR here for a server-wide default
      }
    }
  }
}

⚠️ IMPORTANTE: Caminho Absoluto do Projeto Obrigatório ⚠️

Ao usar qualquer ferramenta deste servidor MCP, você DEVE especificar o CAMINHO ABSOLUTO COMPLETO para o diretório do seu projeto dbt com o parâmetro project_dir. Caminhos relativos não funcionarão corretamente.

// ❌ INCORRECT - Will NOT work
{
  "project_dir": "."
}

// ✅ CORRECT - Will work
{
  "project_dir": "/Users/username/path/to/your/dbt/project"
}

Consulte o guia completo de uso do dbt MCP para instruções e exemplos mais detalhados.

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas MCP:

  • dbt_run: Executar modelos dbt (requer project_dir absoluto)
  • dbt_test: Executar testes dbt (requer project_dir absoluto)
  • dbt_ls: Listar recursos dbt (requer project_dir absoluto)
  • dbt_compile: Compilar modelos dbt (requer project_dir absoluto)
  • dbt_debug: Depurar a configuração do projeto dbt (requer project_dir absoluto)
  • dbt_deps: Instalar dependências de pacotes dbt (requer project_dir absoluto)
  • dbt_seed: Carregar arquivos CSV como dados seed (requer project_dir absoluto)
  • dbt_show: Visualizar resultados do modelo (requer project_dir absoluto)

{ "models": "customers", "project_dir": "/path/to/dbt/project", "limit": 10 } </use_mcp_tool>


### dbt Profiles Configuration

When using the dbt MCP tools, it's important to understand how dbt profiles are handled:

1. The `project_dir` parameter **MUST** be an absolute path (e.g., `/Users/username/project` not `.`) that points to a directory containing both:
   - A valid `dbt_project.yml` file
   - A valid `profiles.yml` file with the profile referenced in the project

2. The MCP server automatically sets the `DBT_PROFILES_DIR` environment variable to the absolute path of the directory specified in `project_dir`. This tells dbt where to look for the profiles.yml file.

3. If you encounter a "Could not find profile named 'X'" error, it means either:
   - The profiles.yml file is missing from the project directory
   - The profiles.yml file doesn't contain the profile referenced in dbt_project.yml
   - You provided a relative path instead of an absolute path for `project_dir`

Example of a valid profiles.yml file:

```yaml
jaffle_shop:  # This name must match the profile in dbt_project.yml
  target: dev
  outputs:
    dev:
      type: duckdb
      path: 'jaffle_shop.duckdb'
      threads: 24

Ao executar comandos por meio do servidor MCP, certifique-se de que o diretório do seu projeto esteja estruturado corretamente com ambos os arquivos de configuração presentes.

Desenvolvimento

Testes de Integração

O projeto inclui testes de integração que verificam a funcionalidade em relação a um projeto dbt real:

# Run all integration tests
python integration_tests/run_all.py

# Run a specific integration test
python integration_tests/test_dbt_run.py

Configuração do Projeto de Teste

Os testes de integração usam o projeto jaffle_shop_duckdb, que está incluído como um submódulo Git no diretório dbt_integration_tests. Quando você clona o repositório com --recurse-submodules conforme mencionado na seção Configuração, isso será inicializado automaticamente.

Se você precisar atualizar o projeto de teste para a versão mais recente do repositório original:

git submodule update --remote dbt_integration_tests/jaffle_shop_duckdb

Se você estiver vendo erros sobre arquivos ausentes no diretório jaffle_shop_duckdb, talvez seja necessário inicializar o submódulo:

git submodule update --init

Licença

MIT