O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Primeiros passos com a extensão do Looker para VS Code

A extensão Looker by Google Cloud para Visual Studio Code (VS Code) permite desenvolver LookML diretamente no seu ambiente de trabalho local. Ele oferece destaque de sintaxe avançado, sincronização bidirecional de arquivos com sua instância do Looker e integração com agentes de programação de IA para "vibe coding".

A extensão é criada usando o framework do Visual Studio Code (VS Code) e oferece suporte a ambientes de desenvolvimento integrados (IDEs) baseados no VS Code, como os seguintes IDEs e ferramentas de programação:

Claude Code
Codex
Cursor
Kiro
VS Code
Windsurf
Zed

Os ambientes de desenvolvimento integrado que não são forks do VS Code, como IntelliJ e Eclipse, não são compatíveis com a extensão do Looker para VS Code.

Este guia mostra como configurar e autenticar a extensão.

Fluxo de trabalho com tecnologia de IA

A extensão do Looker para VS Code faz parte de um fluxo de trabalho de desenvolvimento com agentes habilitados para IA para editar e criar arquivos LookML. Para ativar esse fluxo de trabalho, configure as seguintes ferramentas:

Um IDE local baseado no VS Code. O IDE precisa ter um agente de IA integrado (por exemplo, Cursor) ou, se não tiver, precisa ser integrado a uma ferramenta agêntica independente (como a CLI do Gemini ou o Claude Code). Consulte a documentação do seu ambiente de desenvolvimento integrado local para saber como conectar o ambiente a um agente.
A extensão do Looker para VS Code.
Um servidor MCP, como o servidor MCP gerenciado pelo Looker.

Para saber mais sobre o fluxo de trabalho com tecnologia de IA, consulte a página de documentação Desenvolvimento assistido por IA (programação de vibe) com o Looker.

Antes de começar

Antes de instalar a extensão, atenda aos seguintes requisitos:

Servidor MCP gerenciado pelo Looker (opcional, mas recomendado): se você planeja usar o desenvolvimento assistido por IA, conecte seu ambiente de desenvolvimento integrado e seu agente de IA ao servidor MCP gerenciado pelo Looker. As instruções para configurar o servidor MCP aparecem na página de documentação Servidor MCP gerenciado pelo Looker. Consulte a documentação das ferramentas para mais detalhes.
Permissões do Looker: você precisa ter a permissão develop do Looker para editar os modelos.
Instância do Looker: sua instância precisa estar executando o Looker 26.6 ou uma versão mais recente.
Configuração do projeto: você precisa ter um projeto no Looker (configurado como um repositório simples ou configurado para Git).
Instalação do Git (opcional): se você planeja clonar seu repositório LookML, é necessário ter o Git instalado na sua máquina local.
ID do cliente OAuth: se você estiver usando a autenticação OAuth (recomendada), peça um ID do cliente OAuth ao administrador do Looker.

Configuração do Administrador

Se a organização usa o OAuth para autenticação, um administrador do Looker precisa registrar a extensão do Looker para VS Code como um cliente OAuth na interface de administrador do Looker.

Use o API Explorer do Looker para configurar a integração do OAuth. É possível acessar o API Explorer usando um dos seguintes métodos:

API Explorer instalado

Se a instância do Looker já tiver o API Explorer instalado, acesse-o com este formato de URL:

LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/

O API Explorer não está instalado

Se a sua instância do Looker não tiver o API Explorer, instale-o no Marketplace do Looker. Consulte a página Como usar o API Explorer para saber como instalar a ferramenta.

Instância particular do PSA

Se você estiver usando uma instância de conexões particulares do Looker (Google Cloud Core) que usa o acesso a serviços particulares, o Marketplace do Looker e o APIs Explorer não serão compatíveis. Para registrar um agente de IA, chame o endpoint de API oauth_client_apps diretamente. Se você usar esse método, poderá pular as etapas restantes deste procedimento da API Explorer.

Confira abaixo um exemplo de comando curl que pode ser usado com o endpoint oauth_client_apps para registrar o agente.

curl -X POST "https://LOOKER_INSTANCE_URL/api/4.0/oauth_client_apps/CLIENT_GUID" \
-H "Authorization: token ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "redirect_uri": "REDIRECT_URI",
  "display_name": "CLIENT_NAME",
  "description": "OAuth client to access MCP server using CLIENT_NAME",
  "enabled": true
}'

Para registrar a extensão, siga estas etapas:

Siga as instruções na documentação Registrar um aplicativo cliente OAuth para registrar a extensão.
Para o campo client_guid, siga estas etapas:
- Use qualquer ID globalmente exclusivo.
- Prepare-se para distribuir o ID a todos os desenvolvedores do LookML que quiserem usar a extensão.

Para redirect_uri, insira o URL de callback do seu ambiente de desenvolvimento integrado. Dependendo do seu ambiente de desenvolvimento integrado ou ferramenta de programação, use um dos seguintes URLs de callback:

Ambiente de desenvolvimento integrado ou ferramenta	URL de callback
IDE do Antigravity (disponível no Looker 26.12 ou mais recente)	antigravity-ide://google.vscode-looker-official/oauth_callback
Code-OSS	code-oss://google.vscode-looker-official/oauth_callback
Cursor	cursor://google.vscode-looker-official/oauth_callback
HTTPS	https://google.vscode-looker-official/oauth_callback
Kiro (o suporte ao OAuth para Kiro está disponível no Looker 26.16 ou mais recente)	kiro://google.vscode-looker-official/oauth_callback
Looker	looker://google.vscode-looker-official/oauth_callback
VS Code	vscode://google.vscode-looker-official/oauth_callback
Windsurf	windsurf://google.vscode-looker-official/oauth_callback

Verifique se o campo Ativado está definido como true.
Preencha os campos display_name e description conforme descrito na documentação Registrar um aplicativo cliente OAuth.

Depois que o app for registrado, o API Explorer vai retornar uma resposta com um resumo do registro. Verifique se o URI de redirecionamento corresponde ao que você inseriu no parâmetro de solicitação. Use o endpoint Get OAuth Client App com o valor client_guid para revisar os detalhes do registro.

Forneça o valor client_guid gerado aos desenvolvedores, que vão usá-lo ao configurar a extensão.

Instalar a extensão

A extensão está disponível nos dois principais marketplaces de extensões:

Visual Studio Marketplace (para VS Code padrão)
Open VSX Registry (para Cursor, IDE do Antigravity e VSCodium)

Siga estas etapas para instalar a extensão:

Abra seu ambiente de desenvolvimento integrado, como VS Code ou Cursor.
Clique no ícone Extensões na barra de atividades.
Encontre Looker by Google Cloud e clique em Instalar.
Depois que a extensão for instalada, o ícone Looker vai aparecer na barra de atividades.

Configurar a extensão

Para configurar a extensão com os detalhes da sua instância do Looker, execute o tutorial interativo de integração:

Com um espaço de trabalho aberto, abra a paleta de comandos (Command-Shift-P no macOS ou Ctrl+Shift+P no Windows/Linux).
Execute o comando Looker: Show Onboarding Walkthrough para abrir o tutorial de integração.
Siga as instruções no tutorial para inserir o URL da instância do Looker, o ID do projeto e os detalhes de autenticação. Se você estiver usando um repositório simples, também será solicitado a preencher seu espaço de trabalho com os arquivos LookML do projeto durante esse processo.

Autenticar com o OAuth (recomendado)

O OAuth 2.1 é o fluxo de autenticação recomendado. Quando solicitado durante o tutorial de integração, escolha OAuth e forneça os seguintes valores de configuração:

URL da instância do Looker: o URL da sua instância do Looker.
ID do cliente OAuth: o ID do cliente OAuth (client_guid) que você recebe do administrador do Looker.
ID do projeto: o nome do projeto do LookML que você quer editar. Para encontrar, na sua instância do Looker, abra a página Projetos do LookML. O ID do projeto está na coluna Projeto.

Autenticar com credenciais da API

Se preferir usar chaves de API do Looker, siga a documentação para criar credenciais de API. Quando solicitado durante o tutorial de integração, escolha "Credenciais da API" e forneça os seguintes valores de configuração:

URL da instância do Looker: o URL da sua instância do Looker.
ID do cliente e chave secreta do cliente: o ID e a chave secreta do cliente para as credenciais da API que você está usando para autenticar. Para encontrar essas credenciais, na sua instância do Looker, abra a página Conta. Em seguida, na seção Chaves de API, clique no botão Gerenciar para conferir seus IDs e secrets do cliente.
ID do projeto: o nome do projeto que você quer editar. Para encontrar o nome do projeto, na sua instância do Looker, abra a página Projetos do LookML. O ID do projeto está na coluna Projeto.

Configurações

Embora seja recomendável usar o tutorial de integração, você também pode configurar as definições de extensão no arquivo settings.json do VS Code. Esse arquivo está localizado na pasta .vscode do espaço de trabalho (.vscode/settings.json) ou no arquivo de configurações globais do usuário (settings.json). Também é possível configurar usando o editor visual de configurações do VS Code (Preferências: abrir configurações (UI)).

Todas as propriedades looker.<setting> precisam ser definidas nos arquivos settings.json do VS Code, incluindo a configuração looker.mcpServerUrl do MCP da extensão. Definir essas configurações em um arquivo de configuração do MCP de um agente de IA (como .agents/mcp_config.json) ou em outros arquivos de configurações não funciona com a extensão.

É possível configurar as seguintes opções de extensão em settings.json:

Configuração	Descrição	Padrão
`looker.instanceURL`	URL de base da instância do Looker (por exemplo, `https://mycompany.looker.com`).	-
`looker.authURL`	URL a ser usado para autenticação OAuth. Só defina se for diferente do URL da sua instância.	`looker.instanceURL`
`looker.sdkURL`	URL a ser usado para solicitações de API. Só defina se for diferente do URL da sua instância.	`looker.instanceURL`
`looker.oauthClientId`	ID do cliente OAuth do Looker. Obrigatório para OAuth.	-
`looker.clientId`	ID do cliente da API Looker. Obrigatório para a autenticação com chave de API.	-
`looker.clientSecret`	Chave secreta do cliente da API Looker. Obsoleto. Use o tutorial de integração para configurar as credenciais da API.	-
`looker.projectId`	ID do projeto do LookML.	-
`looker.mcpServerUrl`	URL do servidor MCP de destino para onde o proxy MCP local da extensão encaminha as solicitações. Definido apenas se for diferente de `looker.instanceURL/mcp` (por exemplo, `http://localhost:5000/mcp`).	`looker.instanceURL/mcp`
`looker.acceptSelfSignedCertificates`	Ignorar erros de certificado SSL (por exemplo, para certificados autoassinados). Aviso: não recomendamos ativar essa opção.	`false`
`looker.askBeforeOverwritingRemote`	Sempre perguntar antes de substituir arquivos remotos quando um conflito é detectado.	`false`

Configurar o cliente MCP

Para permitir que o agente de IA interaja com o Looker pela extensão, configure o agente para se conectar ao proxy MCP local da extensão em http://127.0.0.1:5050/mcp.

Seu agente de IA faz referência ao próprio arquivo de configuração do MCP (como .agents/mcp_config.json no VS Code, .mcp.json no Claude Code ou .cursor/mcp.json no Cursor). Apontar essa configuração para o proxy local permite que a extensão capture as solicitações de MCP do seu agente e as encaminhe com os cabeçalhos de autenticação adequados.

Servidor MCP gerenciado pelo Looker (padrão e recomendado)

A extensão executa um proxy reverso local (padrão: http://127.0.0.1:5050/mcp) que se conecta ao servidor MCP gerenciado integrado do Looker (LOOKER_INSTANCE_URL/mcp). O proxy injeta automaticamente tokens de portador OAuth e armazena em buffer as solicitações de ferramentas do agente de IA até que as sincronizações de arquivos locais pendentes sejam concluídas. Isso garante que as ferramentas de validação nunca avaliem código desatualizado no servidor.

Servidor MCP personalizado ou auto-hospedado (opcional)

Se a organização hospeda um servidor MCP personalizado (como a MCP Toolbox for Databases independente):

Nas configurações do VS Code, defina looker.mcpServerUrl como o URL do seu servidor personalizado (por exemplo, http://localhost:5000/mcp).
Configure o cliente MCP do seu ambiente de desenvolvimento integrado para apontar para o proxy de extensão em http://127.0.0.1:5050/mcp.

Visual Studio Code (Copilot)

Abra o VS Code e crie o diretório .agents na raiz do projeto, se ele ainda não existir.
Crie e abra o arquivo .agents/mcp_config.json, se ele ainda não existir.
Adicione a seguinte configuração e salve o arquivo:

      {
        "mcpServers": {
          "Looker": {
            "serverUrl": "http://127.0.0.1:5050/mcp",
            "disabledTools": [
              "query_url",
              "get_looks",
              "run_look",
              "make_look",
              "get_dashboards",
              "run_dashboard",
              "make_dashboard",
              "add_dashboard_element",
              "add_dashboard_filter",
              "generate_embed_url",
              "health_pulse",
              "health_analyze",
              "health_vacuum",
              "get_project_files",
              "get_project_file",
              "create_project_file",
              "update_project_file",
              "delete_project_file",
              "get_project_directories",
              "create_project_directory",
              "delete_project_directory",
              "project_git_branch"
            ]
          }
        }
      }

Claude Code

Crie o arquivo .mcp.json na raiz do projeto, se ele ainda não existir.
Adicione a seguinte configuração e salve o arquivo:

      {
        "mcpServers": {
          "Looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050/mcp"
          }
        }
      }

Cursor

Crie o diretório .cursor na raiz do projeto, se ele ainda não existir.
Crie e abra o arquivo .cursor/mcp.json, se ele ainda não existir.
Adicione a seguinte configuração e salve o arquivo:

      {
        "mcpServers": {
          "Looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050/mcp"
          }
        }
      }

Abra Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.

Cline

Abra a extensão Cline no VS Code e clique no ícone Servidores MCP.
Clique em Configurar servidores MCP para abrir o arquivo de configuração.
Adicione a seguinte configuração e salve o arquivo:

      {
        "mcpServers": {
          "Looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050/mcp"
          }
        }
      }

Windsurf

Abra o Windsurf e navegue até o assistente do Cascade.
Clique no ícone do MCP e em Configurar para abrir o arquivo de configuração.
Adicione a seguinte configuração e salve o arquivo:

      {
        "mcpServers": {
          "Looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050/mcp"
          }
        }
      }

Autenticar pelo Looker

Se você estiver usando a autenticação OAuth, faça login para vincular seu IDE local à sua conta do Looker.

Abra a paleta de comandos.
Execute o comando: Looker: fazer login (OAuth).
Confirme a solicitação para abrir o navegador.
No navegador, autorize a extensão a acessar sua conta do Looker.
Depois de autorizar, o navegador redireciona você de volta para o ambiente de desenvolvimento integrado. Você vai receber uma notificação informando Login no Looker feito com sucesso!

Preencher seu projeto local do LookML

Para começar o desenvolvimento, abra seu projeto do LookML no ambiente de desenvolvimento integrado local usando o método adequado para a configuração do repositório:

Repositório do Git

Se o projeto do LookML estiver configurado para Git, siga estas etapas:

No VS Code, abra uma nova janela.
Abra a paleta de comandos e selecione Git: Clone.
Insira o URL do seu repositório Git remoto (por exemplo, do GitHub ou GitLab) e escolha uma pasta local.
Abra a pasta clonada no seu IDE.

Modo de repositório simples

Se o projeto do LookML estiver configurado como um repositório simples, siga estas etapas:

Com um espaço de trabalho aberto, crie e abra uma pasta local vazia para seu projeto.
Abra a paleta de comandos (Command-Shift-P no macOS ou Ctrl+Shift+P no Windows/Linux).
Execute o comando Looker: Show Onboarding Walkthrough para abrir o tutorial de integração.
Na etapa Selecionar projeto, escolha o projeto do LookML em que você quer trabalhar e clique em Próxima.
A extensão reconhece que sua pasta local está vazia e pede para você preencher o espaço de trabalho com os arquivos do projeto. Clique em Preencher espaço de trabalho.
Conclua o tutorial de integração.

Depois que o espaço de trabalho é preenchido, a extensão começa a sincronizar automaticamente sua pasta local com a ramificação extraída no modo de desenvolvimento da instância do Looker.

Solução de problemas

É possível conferir os registros de extensão no painel Saída do seu ambiente de desenvolvimento integrado. Selecione o canal Looker para ver os registros. Para registros mais detalhados, abra a paleta de comandos, execute o comando Desenvolvedor: definir nível de registro e selecione Depurar ou Trace.

Erros de autenticação: verifique se seu looker.instanceURL e looker.oauthClientId estão corretos. Verifique se o URI de redirecionamento no Looker corresponde exatamente.
Problemas de sincronização: verifique os registros de extensão para resolver problemas de sincronização. Para ver os registros, abra o painel Saída e selecione Looker no menu suspenso.
Resposta de solicitação inválida durante o OAuth: verifique se a instância do Looker está acessível na sua rede local e se você tem uma conexão de Internet válida.

Se você tiver problemas com a extensão, execute o comando Desenvolvedor: recarregar janela na paleta de comandos para resolver.