Usar a MCP Toolbox for Databases
Nesta página, mostramos como usar a MCP Toolbox for Databases e conectar sua instância do Looker a ambientes de desenvolvimento integrado (IDEs) e ferramentas para desenvolvedores que oferecem suporte ao Protocolo de Contexto de Modelo (MCP). A caixa de ferramentas do MCP é uma boa opção se você estiver usando uma instância hospedada pelo cliente ou se preferir gerenciar sua própria infraestrutura. Caso contrário, recomendamos usar o servidor MCP gerenciado pelo Looker.
Recomendamos usar a extensão dedicada do Looker para a CLI do Gemini com o MCP Toolbox. Use a camada semântica do Looker para fornecer à CLI do Gemini acesso seguro, controlado e sob demanda a dados confiáveis e acelere os fluxos de trabalho automatizando a criação de relatórios, visualizações e painéis com comandos em linguagem natural. Como a interface de linha de comando de próxima geração do Google Cloud, a CLI do Gemini é a ferramenta recomendada para interagir com suas instâncias do Looker na linha de comando.
Você também pode conectar outros ambientes de desenvolvimento integrado (IDEs) e ferramentas de desenvolvedor que oferecem suporte ao Protocolo de Contexto de Modelo (MCP) usando a MCP Toolbox for Databases de uso geral. A MCP Toolbox é um servidor MCP de código aberto que simplifica a conexão de agentes de IA aos seus dados, lidando com complexidades como autenticação e pool de conexões. Assim, você pode interagir com seus dados usando a linguagem natural diretamente do seu ambiente de desenvolvimento integrado (IDE, na sigla em inglês). Para essas ferramentas, esse método oferece recursos principais de interação com o banco de dados.
Sobre a CLI do Gemini e as extensões
A CLI do Gemini é um agente de IA de código aberto projetado para acelerar os fluxos de trabalho de desenvolvimento, ajudando na programação, depuração, análise de dados e criação de conteúdo. A missão dele é oferecer uma experiência elegante para interagir com serviços de nuvem de dados e bancos de dados de código aberto conhecidos.
Como as extensões funcionam
A CLI do Gemini é altamente extensível, permitindo a adição de novas ferramentas e recursos por meio de extensões. Essas extensões são fáceis de instalar. É possível carregá-los de um URL do GitHub, um diretório local ou um registro configurável. Essas extensões oferecem um conjunto avançado de recursos, incluindo novas ferramentas, comandos de barra e comandos para simplificar seu fluxo de trabalho.
Preparar a autenticação do Looker
Há duas opções para autenticar seu cliente MCP com o Looker: usar credenciais de API padrão ou autenticar o cliente com um registro de aplicativo OAuth.
Opção 1: credenciais da API
- Receba um ID e uma chave secreta do cliente do Looker. Siga as instruções na página de documentação Autenticação da API Looker.
- Tenha o URL de base da sua instância do Looker disponível. Provavelmente é algo como
https://looker.example.com. Em alguns casos, a API detecta uma porta diferente, e você precisa usarhttps://looker.example.com:19999.
Opção 2: registro de aplicativos OAuth
Abra o Looker API Explorer.
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_appsdiretamente. Se você usar esse método, poderá pular as etapas restantes deste procedimento da API Explorer.Confira um exemplo de comando
curlque pode ser usado com o endpointoauth_client_appspara 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 }'No método Auth, encontre o endpoint de API Registrar app OAuth. Você também pode pesquisar "app oauth" no campo Pesquisar.
Selecione Executar.
Para
client_guid, insira uma string personalizada, por exemplo,gemini_cliouclaude-desktop.No corpo da solicitação, insira a seguinte configuração JSON:
{ "redirect_uri": "AI_AGENT_REDIRECT_URI", "display_name": "APPLICATION_NAME", "description": "APPLICATION_DESCRIPTION", "enabled": true }Substitua:
AI_AGENT_REDIRECT_URI: o URI de redirecionamento da extensão do seu agente de IA ou aplicativo de serviço compartilhado.- Para aplicativos hospedados na nuvem, ele pode parecer um URL HTTPS seguro:
https://AI_AGENT_URL/oauth2callback Para aplicativos executados localmente, ele precisa ser um URL localhost com uma porta estática:
http://localhost:7777/oauth/callbackPara IDEs, pode ter esta aparência:
vscode://google.vscode-looker-official/oauth_callback
- Para aplicativos hospedados na nuvem, ele pode parecer um URL HTTPS seguro:
APPLICATION_NAME: o nome de exibição do seu aplicativo OAuth. Por exemplo,Claude Desktop.APPLICATION_DESCRIPTION: uma breve descrição do seu aplicativo OAuth.
Marque a caixa de confirmação ao lado de Entendo que este endpoint de API vai mudar os dados e selecione Executar.
Instalar o MCP Toolbox
Faça o download da versão mais recente da MCP Toolbox como um binário. Selecione o binário que corresponde à arquitetura do SO e da CPU. Use a versão V1.0.0 ou mais recente da caixa de ferramentas do MCP.
linux/amd64
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/linux/amd64/toolbox
darwin/arm64
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/darwin/arm64/toolbox
darwin/amd64
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/darwin/amd64/toolbox
windows/amd64
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/windows/amd64/toolbox.exe
Torne o binário executável.
chmod +x toolboxVerifique a instalação.
./toolbox --version
Executar o MCP Toolbox como um serviço compartilhado
Para clientes do MCP que exigem autenticação OAuth por HTTPS, implante o MCP Toolbox atrás de um proxy reverso HTTPS, como o Cloud Run. O proxy reverso encerra o SSL e encaminha as solicitações para o contêiner da MCP Toolbox.
Configurar o ambiente do servidor
Defina as seguintes variáveis de ambiente na sua implantação:
LOOKER_BASE_URL=YOUR_LOOKER_BASE_URLLOOKER_USE_CLIENT_OAUTH=true
Execute a MCP Toolbox com os seguintes argumentos:
--prebuilt=looker,looker-dev--mcp-prm-file=prm.json[--address=0.0.0.0][--port=8080]
A MCP Toolbox normalmente detecta a porta
5000do127.0.0.1. Se o proxy reverso estiver em outro host, use--address=0.0.0.0para vincular a todos os endereços IP. Use a configuração--port=se precisar usar uma porta de detecção diferente de5000. Por exemplo, o Cloud Run encaminha automaticamente o tráfego externo da porta443, a porta HTTPS, para8080.Crie um arquivo de configuração de metadados de recurso protegido (PRM, na sigla em inglês) (
prm.json) com a seguinte estrutura:{ "resource": "https://PROXY_URL/mcp", "authorization_servers": ["LOOKER_URL"], "scopes_supported": ["cors_api"] }Substitua:
PROXY_URL: o domínio e o caminho de base do servidor proxy reverso.LOOKER_URL: o URL base da sua instância do Looker.
Para um exemplo de como configurar o cliente ao executar a MCP Toolbox como um serviço compartilhado, consulte o exemplo Configuração do Claude Desktop.
Configurar o cliente MCP
Esta seção descreve como configurar várias ferramentas de desenvolvedor para se conectar à sua instância do Looker usando a MCP Toolbox for Databases. A caixa de ferramentas funciona como um servidor Protocolo de Contexto de Modelo (MCP) de código aberto que fica entre seu IDE e seu banco de dados, fornecendo um plano de controle seguro e eficiente para suas ferramentas de IA. Selecione a guia da sua ferramenta específica para conferir as instruções de configuração.
- CLI do Gemini
- Gemini Code Assist
- Claude Code
- Claude para computador
- Cline (extensão do VS Code)
- Cursor
- Visual Studio Code (Copilot)
- Windsurf (Codium)
CLI do Gemini
Escolha o método de conexão com base na sua opção de autenticação:
Opção 1: credenciais da API com extensão
- Instale a CLI do Gemini.
- Instale a extensão do Looker para a CLI do Gemini no repositório do GitHub usando o seguinte comando:
gemini extensions install https://github.com/gemini-cli-extensions/looker
- Defina variáveis de ambiente para se conectar à sua instância do Looker, substituindo as seguintes variáveis de ambiente pelos seus valores:
LOOKER_URL: o URL da sua instância do Looker.CLIENT_IDeCLIENT_SECRET: a chave de API usada para acessar a API do Looker.VERIFY_SSL:trueoufalse, dependendo se você usa criptografia SSL para conectar seu banco de dados à instância do Looker.
export LOOKER_BASE_URL="LOOKER_URL" export LOOKER_CLIENT_ID="CLIENT_ID" export LOOKER_CLIENT_SECRET="CLIENT_SECRET" export LOOKER_VERIFY_SSL="VERIFY_SSL"
- Inicie a CLI do Gemini no modo interativo:
A CLI carrega automaticamente a extensão do Looker para a extensão da CLI do Gemini e as ferramentas dela, que você pode usar para interagir com sua instância do Looker.gemini
Opção 2: serviço compartilhado remoto com OAuth
Para se conectar a um serviço compartilhado remoto usando o OAuth, não instale a extensão do Looker. Em vez disso, configure a CLI do Gemini para se conectar diretamente ao servidor MCP remoto.
- Instale a CLI do Gemini.
- Adicione o servidor MCP remoto usando o comando a seguir, substituindo
PROXY_URLpelo domínio do seu servidor proxy reverso:gemini mcp add --transport http looker https://PROXY_URL/mcp
Como alternativa, você pode configurar isso manualmente adicionando a seguinte configuração ao arquivo
settings.json(localizado em~/.gemini/settings.jsonou no diretório do projeto):{ "mcpServers": { "looker": { "httpUrl": "https://PROXY_URL/mcp" } } } - Inicie a CLI do Gemini no modo interativo:
Quando solicitado a se conectar, a CLI inicia o fluxo de autorização do OAuth para autenticar com segurança sua instância do Looker.gemini
Gemini Code Assist
Recomendamos configurar o Gemini Code Assist para usar a CLI do Gemini. Essa abordagem elimina a necessidade de configurar manualmente um servidor MCP.
- Verifique se você instalou e configurou a CLI do Gemini e a extensão
looker(para credenciais da API) ou uma configuração de servidor MCP remoto (para serviço compartilhado com OAuth). - Configure o Gemini Code Assist para usar a CLI do Gemini.
- Comece a interagir com sua instância do Looker usando linguagem natural diretamente na conversa do Gemini Code Assist.
Código do Claude
Escolha o método de conexão com base na sua opção de autenticação:
Opção 1: credenciais da API
- Instale o Claude Code.
- Crie o arquivo
.mcp.jsonna raiz do projeto, se ele não existir. - Adicione a seguinte configuração, substituindo as variáveis de ambiente pelos seus valores e salve.
LOOKER_URL: o URL da sua instância do Looker.CLIENT_IDeCLIENT_SECRET: a chave de API usada para acessar a API do Looker.VERIFY_SSL:trueoufalse, dependendo se você usa criptografia SSL para conectar seu banco de dados à instância do Looker.
{
"mcpServers": {
"looker-toolbox": {
"command": "./PATH/TO/toolbox",
"args": ["--stdio", "--prebuilt", "looker"],
"env": {
"LOOKER_BASE_URL": "LOOKER_URL",
"LOOKER_CLIENT_ID": "CLIENT_ID",
"LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
"LOOKER_VERIFY_SSL": "VERIFY_SSL",
}
}
}
}
Opção 2: serviço compartilhado remoto com OAuth
- Instale o Claude Code.
- Crie o arquivo
.mcp.jsonna raiz do projeto, se ele não existir. - Adicione a configuração a seguir, substituindo
PROXY_URLpelo domínio do seu servidor proxy reverso e salve.
{
"mcpServers": {
"looker-toolbox": {
"type": "http",
"url": "https://PROXY_URL/mcp"
}
}
}
Claude para computador
Escolha o método de conexão com base na sua opção de autenticação:
Opção 1: credenciais da API
- Abra o Claude para computador e acesse Configurações.
- Na guia Desenvolvedor, clique em Editar configuração para abrir o arquivo de configuração.
- Adicione a seguinte configuração, substituindo as variáveis de ambiente pelos seus valores e salve.
LOOKER_URL: o URL da sua instância do Looker.CLIENT_IDeCLIENT_SECRET: a chave de API usada para acessar a API do Looker.VERIFY_SSL:trueoufalse, dependendo se você usa criptografia SSL para conectar seu banco de dados à instância do Looker.
{
"mcpServers": {
"looker-toolbox": {
"command": "./PATH/TO/toolbox",
"args": ["--stdio", "--prebuilt", "looker"],
"env": {
"LOOKER_BASE_URL": "LOOKER_URL",
"LOOKER_CLIENT_ID": "CLIENT_ID",
"LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
"LOOKER_VERIFY_SSL": "VERIFY_SSL",
}
}
}
}
Opção 2: serviço compartilhado remoto com OAuth
- No Claude para computador, acesse Configurações e selecione Conectores.
- Escolha Adicionar conector personalizado e insira um nome (por exemplo, Looker).
- No URL, insira o endpoint do servidor proxy reverso com o caminho
/mcpanexado (por exemplo,https://looker-mcp-toolbox.example.com/mcp). - Em Configurações avançadas, insira a string exata que você usou para o
client_guiddurante o registro do app OAuth. Deixe a chave secreta do cliente OAuth em branco. - Selecione Adicionar para salvar o conector. Quando solicitado a se conectar, o Claude para computador inicia com segurança o fluxo de autorização PKCE pelo navegador.
- Reinicie o Claude para computador.
Cline
Escolha o método de conexão com base na sua opção de autenticação:
Opção 1: credenciais da API
- 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, substituindo as variáveis de ambiente pelos seus valores e salve.
LOOKER_URL: o URL da sua instância do Looker.CLIENT_IDeCLIENT_SECRET: a chave de API usada para acessar a API do Looker.VERIFY_SSL:trueoufalse, dependendo se você usa criptografia SSL para conectar seu banco de dados à instância do Looker.
{
"mcpServers": {
"looker-toolbox": {
"command": "./PATH/TO/toolbox",
"args": ["--stdio", "--prebuilt", "looker"],
"env": {
"LOOKER_BASE_URL": "LOOKER_URL",
"LOOKER_CLIENT_ID": "CLIENT_ID",
"LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
"LOOKER_VERIFY_SSL": "VERIFY_SSL",
}
}
}
}
Opção 2: serviço compartilhado remoto com OAuth
- 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 configuração a seguir, substituindo
PROXY_URLpelo domínio do seu servidor proxy reverso e salve.
{
"mcpServers": {
"looker-toolbox": {
"type": "http",
"url": "https://PROXY_URL/mcp"
}
}
}
Cursor
Escolha o método de conexão com base na sua opção de autenticação:
Opção 1: credenciais da API
- Crie o diretório
.cursorna raiz do projeto, se ele não existir. - Crie o arquivo
.cursor/mcp.json, se ele não existir, e abra-o. - Adicione a seguinte configuração, substituindo as variáveis de ambiente pelos seus valores e salve.
LOOKER_URL: o URL da sua instância do Looker.CLIENT_IDeCLIENT_SECRET: a chave de API usada para acessar a API do Looker.VERIFY_SSL:trueoufalse, dependendo se você usa criptografia SSL para conectar seu banco de dados à instância do Looker.
{
"mcpServers": {
"looker-toolbox": {
"command": "./PATH/TO/toolbox",
"args": ["--stdio", "--prebuilt", "looker"],
"env": {
"LOOKER_BASE_URL": "LOOKER_URL",
"LOOKER_CLIENT_ID": "CLIENT_ID",
"LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
"LOOKER_VERIFY_SSL": "VERIFY_SSL",
}
}
}
}
- Abra Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.
Opção 2: serviço compartilhado remoto com OAuth
- Crie o diretório
.cursorna raiz do projeto, se ele não existir. - Crie o arquivo
.cursor/mcp.json, se ele não existir, e abra-o. - Adicione a configuração a seguir, substituindo
PROXY_URLpelo domínio do seu servidor proxy reverso e salve.
{
"mcpServers": {
"looker-toolbox": {
"type": "http",
"url": "https://PROXY_URL/mcp"
}
}
}
- Abra Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.
Visual Studio Code (Copilot)
Escolha o método de conexão com base na sua opção de autenticação:
Opção 1: credenciais da API
- Abra o VS Code e crie o diretório
.vscodena raiz do projeto, se ele não existir. - Crie o arquivo
.vscode/mcp.json, se ele não existir, e abra-o. - Adicione a seguinte configuração, substituindo as variáveis de ambiente pelos seus valores e salve.
LOOKER_URL: o URL da sua instância do Looker.CLIENT_IDeCLIENT_SECRET: a chave de API usada para acessar a API do Looker.VERIFY_SSL:trueoufalse, dependendo se você usa criptografia SSL para conectar seu banco de dados à instância do Looker.
{
"servers": {
"looker-toolbox": {
"command": "./PATH/TO/toolbox",
"args": ["--stdio", "--prebuilt", "looker"],
"env": {
"LOOKER_BASE_URL": "LOOKER_URL",
"LOOKER_CLIENT_ID": "CLIENT_ID",
"LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
"LOOKER_VERIFY_SSL": "VERIFY_SSL",
}
}
}
}
Opção 2: serviço compartilhado remoto com OAuth
- Abra o VS Code e crie o diretório
.vscodena raiz do projeto, se ele não existir. - Crie o arquivo
.vscode/mcp.json, se ele não existir, e abra-o. - Adicione a configuração a seguir, substituindo
PROXY_URLpelo domínio do seu servidor proxy reverso e salve.
{
"servers": {
"looker-toolbox": {
"type": "http",
"url": "https://PROXY_URL/mcp"
}
}
}
Windsurf
Escolha o método de conexão com base na sua opção de autenticação:
Opção 1: credenciais da API
- 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, substituindo as variáveis de ambiente pelos seus valores e salve.
LOOKER_URL: o URL da sua instância do Looker.CLIENT_IDeCLIENT_SECRET: a chave de API usada para acessar a API do Looker.VERIFY_SSL:trueoufalse, dependendo se você usa criptografia SSL para conectar seu banco de dados à instância do Looker.
{
"mcpServers": {
"looker-toolbox": {
"command": "./PATH/TO/toolbox",
"args": ["--stdio", "--prebuilt", "looker"],
"env": {
"LOOKER_BASE_URL": "LOOKER_URL",
"LOOKER_CLIENT_ID": "CLIENT_ID",
"LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
"LOOKER_VERIFY_SSL": "VERIFY_SSL",
}
}
}
}
Opção 2: serviço compartilhado remoto com OAuth
- 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 configuração a seguir, substituindo
PROXY_URLpelo domínio do seu servidor proxy reverso e salve.
{
"mcpServers": {
"looker-toolbox": {
"type": "http",
"url": "https://PROXY_URL/mcp"
}
}
}
Usar ferramentas de IA
Sua ferramenta de IA agora está conectada ao Looker usando o MCP. Peça ao seu assistente de IA para listar modelos, análises detalhadas, dimensões e medidas. Você também pode executar uma consulta recuperando o SQL de uma consulta ou executando um Look salvo.
As seguintes ferramentas estão disponíveis para o LLM:
Ferramentas de consulta e modelos do Looker
Essas ferramentas são usadas para receber informações sobre um modelo do Looker e executar consultas nele.
get_models: liste todos os modelos do LookML na sua instância do Looker.get_explores: lista as análises detalhadas em um determinado modelo.get_dimensions: lista as dimensões em uma análise específica.get_measures: lista as medidas em uma análise específica.get_filters: lista os filtros em uma análise detalhada.get_parameters: lista os parâmetros em uma análise detalhada específica.query: execute uma consulta e retorne os dados.query_sql: retorna o SQL gerado pelo Looker para uma consulta.query_url: retorna um link para a consulta no Looker para mais análises.
Ferramentas de conteúdo do Looker
Essas ferramentas salvam conteúdo (Looks e dashboards) de uma instância do Looker e criam novos conteúdos salvos.
get_looks: retorna os Looks salvos que correspondem a um título ou descrição.run_look: executa uma análise salva e retorna os dados.make_look: crie um Look salvo no Looker e retorne o URL.get_dashboards: retorna os painéis salvos que correspondem a um título ou descrição.make_dashboard: crie um painel salvo no Looker e retorne o URL.add_dashboard_element: adicione um bloco a um painel.
Ferramentas de integridade da instância do Looker
Essas ferramentas oferecem os mesmos algoritmos de verificação de integridade da CLI Henry.
health_pulse: confira a integridade de uma instância do Looker.health_analyze: analise o uso de um objeto do Looker.health_vacuum: encontre elementos da LookML que podem não estar sendo usados.
Ferramentas de criação do LookML
Essas ferramentas permitem que o caller escreva e modifique arquivos LookML, além de receber o esquema de banco de dados necessário para escrever LookML de maneira eficaz.
dev_mode: ative e desative o Modo de desenvolvimento para a sessão. A criação de LookML precisa ser feita no modo de desenvolvimento. As consultas executadas no modo de desenvolvimento usam o LookML modificado para que você possa testar o impacto das mudanças.get_projects: receba a lista de projetos do LookML disponíveis.get_project_files: recebe a lista de arquivos do LookML em um projeto.get_project_file: recebe o conteúdo de um arquivo do LookML.create_project_file: crie um arquivo do LookML.update_project_file: modifique um arquivo do LookML.delete_project_file: exclui um arquivo do LookML.get_connections: receba a lista de conexões.get_connection_schemas: recebe a lista de esquemas de uma conexão.get_connection_databases: receba a lista de bancos de dados de uma conexão.get_connection_tables: recebe a lista de tabelas de uma conexão.get_connection_table_columns: recebe a lista de colunas de uma tabela em uma conexão.