Use Looker with MCP, Gemini CLI and other Agents

This page shows you how to connect your Looker instance to various developer tools.

For the most powerful and integrated experience, we recommend using the dedicated Looker extension for Gemini CLI. Use Looker's semantic layer to provide the Gemini CLI with secure, governed, and on-demand access to trusted data, and accelerate workflows by automating the creation of reports, visualizations, and dashboards from natural language prompts. As Google Cloud's next-generation command-line interface, the Gemini CLI is the recommended tool for interacting with your Looker instances from the command line.

You can also connect other integrated development environments (IDEs) and developer tools that support the Model Context Protocol (MCP) by using the general-purpose MCP Toolbox for Databases. The MCP Toolbox is an open-source MCP server that simplifies connecting AI agents to your data by handling complexities like authentication and connection pooling, which lets you interact with your data using natural language directly from your IDE. For these tools, this method provides core database interaction capabilities.

About Gemini CLI and extensions

Gemini CLI is an open-source AI agent that's designed to accelerate development workflows by assisting with coding, debugging, data exploration, and content creation. Its mission is to provide an elegant agentic experience for interacting with data cloud services and popular open-source databases.

How extensions work

Gemini CLI is highly extensible, allowing for the addition of new tools and capabilities through extensions. These extensions are straightforward to install. You can load them from a GitHub URL, a local directory, or a configurable registry. These extensions provide a rich set of capabilities, including new tools, slash commands, and prompts to streamline your workflow.

Prepare Looker authentication

You can authenticate your MCP client with Looker by using either standard API credentials or through an OAuth application registration.

Option 1: API credentials

1. Get a Looker Client ID and Client Secret. Follow the directions on the Looker API authentication documentation page.
2. Have the base URL of your Looker instance available. It is likely something like https://looker.example.com. In some cases the API is listening at a different port, and you will need to use https://looker.example.com:19999 instead.

Option 2: OAuth application registration

1. Open the Looker API Explorer.

   API Explorer installed

   If your Looker instance already has the API Explorer installed, you can access it with this URL format:

   https://LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/
   

   API Explorer not installed

   If your Looker instance doesn't have the API Explorer, you can install it from the Looker Marketplace. See the Using the API Explorer page for information about how to install the API Explorer.

   PSA private instance

   If you are using a Looker (Google Cloud core) private connections instance that uses private services access, the Looker Marketplace and API Explorer aren't supported. To register an AI agent, you must call the oauth_client_apps API endpoint directly. If you use this method, you can skip the remaining steps of this API Explorer procedure.

   The following is an example of a curl command that you can use with the oauth_client_apps endpoint to register the agent.

   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
   }'
   

2. Under the Auth method, find the Register OAuth App API endpoint. You can also search for "oauth app" in the Search field.

3. Select Run It.

4. For the client_guid, enter a custom string (for example, gemini_cli or claude-desktop).

5. In the request body, enter the following JSON configuration:

   {
     "redirect_uri": "AI_AGENT_REDIRECT_URI",
     "display_name": "APPLICATION_NAME",
     "description": "APPLICATION_DESCRIPTION",
     "enabled": true
   }
   

   Replace the following:

   • AI_AGENT_REDIRECT_URI: The redirect URI for your AI agent extension or shared service application.

     • For Cloud-hosted applications, it may look like a secure HTTPS URL: https://AI_AGENT_URL/oauth2callback

     • For applications running locally, it should be a localhost URL with a static port: http://localhost:7777/oauth/callback

     • For IDEs, it may look like the following: vscode://google.vscode-looker-official/oauth_callback

   • APPLICATION_NAME: The display name for your OAuth application—for example, Claude Desktop.

   • APPLICATION_DESCRIPTION: A short description of your OAuth application.

6. Check the confirmation box next to I understand that this API endpoint will change data, and then select Run.

Install MCP Toolbox

1. Download the latest version of MCP Toolbox as a binary. Select the binary that corresponds to your OS and CPU architecture. You must use MCP Toolbox version V1.0.0 or later.

   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
   
   

2. Make the binary an executable.

   chmod +x toolbox
   

3. Verify the installation.

   ./toolbox --version
   

Run MCP Toolbox as a shared service

For MCP clients that require OAuth authentication over HTTPS, you must deploy the MCP Toolbox behind an HTTPS reverse proxy (such as Cloud Run). The reverse proxy terminates SSL and forwards requests to the MCP Toolbox container.

Configure the server environment

1. Set the following environment variables in your deployment:

   • LOOKER_BASE_URL=YOUR_LOOKER_BASE_URL
   • LOOKER_USE_CLIENT_OAUTH=true

2. Run the MCP Toolbox with the following arguments:

   • --prebuilt=looker,looker-dev
   • --mcp-prm-file=prm.json
   • [--address=0.0.0.0]
   • [--port=8080]

   MCP Toolbox normally listens on 127.0.0.1 port 5000. If the reverse proxy is on another host, use --address=0.0.0.0 to bind to all IP addresses. Use the --port= setting if you need to use a listening port other than 5000. For example, Cloud Run automatically forwards external traffic from port 443, the HTTPS port, to 8080.

3. Create a Protected Resource Metadata (PRM) configuration file (prm.json) with the following structure:

   {
   "resource": "https://PROXY_URL/mcp",
   "authorization_servers": ["LOOKER_URL"],
   "scopes_supported": ["cors_api"]
   }
   

   Replace the following:

   • PROXY_URL: The domain and base path of your reverse proxy server.
   • LOOKER_URL: The base URL of your Looker instance.

For an example of how to configure the client when you're running MCP Toolbox as a shared service, see the example Claude desktop configuration.

Configure the MCP client

This section describes how to configure various developer tools to connect to your Looker instance using the MCP Toolbox for Databases. The toolbox acts as an open-source Model Context Protocol (MCP) server that sits between your IDE and your database, providing a secure and efficient control plane for your AI tools. Select the tab for your specific tool to see the configuration instructions.

• Gemini CLI
• Gemini Code Assist
• Claude code
• Claude desktop
• Cline (VS Code extension)
• Cursor
• Visual Studio Code (Copilot)
• Windsurf (Codium)

      {
        "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",
          }
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

      {
        "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",
          }
          }
        }
      }
  

      {
        "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",
          }
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

      {
        "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",
          }
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

      {
        "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",
          }
          }
        }
      }
  

      {
        "servers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

      {
        "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",
          }
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

Use AI tools

Your AI tool is now connected to Looker using MCP. Try asking your AI assistant to list models, Explores, dimensions, and measures. You can also run a query by retrieving the SQL for a query or running a saved Look.

The following tools are available to the LLM:

Looker Model and Query Tools

These tools are used to get information about a Looker model and execute queries against that model.

• get_models: List all LookML models on your Looker instance.
• get_explores: List the explores in a given model.
• get_dimensions: List the dimensions in a given Explore.
• get_measures: List the measures in a given Explore.
• get_filters: List the filters in a given Explore.
• get_parameters: List the parameters in a given Explore.
• query: Run a query and return the data.
• query_sql: Return the SQL that is generated by Looker for a query.
• query_url: Return a link to the query in Looker for further exploration.

Looker Content Tools

These tools get saved content (Looks and Dashboards) from a Looker instance and create new saved content.

• get_looks: Return the saved Looks that match a title or description.
• run_look: Run a saved Look and return the data.
• make_look: Create a saved Look in Looker and return the URL.
• get_dashboards: Return the saved dashboards that match a title or description.
• make_dashboard: Create a saved dashboard in Looker and return the URL.
• add_dashboard_element: Add a tile to a dashboard.

Looker Instance Health Tools

These tools offer the same health check algorithms that the popular CLI Henry offers.

• health_pulse: Check the health of a Looker instance.
• health_analyze: Analyze the usage of a Looker object.
• health_vacuum: Find LookML elements that might be unused.

LookML Authoring Tools

These tools allow enable the caller to write and modify LookML files as well as get the database schema needed to write LookML effectively.

• dev_mode: Turn Development Mode on and off for the session. LookML authoring must be done in Development Mode. Queries that are run in Development Mode use the modified LookML so you can test the impact of your changes.
• get_projects: Get the list of available LookML projects.
• get_project_files: Get the list of LookML files in a project.
• get_project_file: Get the content of a LookML file.
• create_project_file: Create a new LookML file.
• update_project_file: Modify an existing LookML file.
• delete_project_file: Delete a LookML file.
• get_connections: Get the list of connections.
• get_connection_schemas: Get the list of schemas for a connection.
• get_connection_databases: Get the list of databases for a connection.
• get_connection_tables: Get the list of tables for a connection.
• get_connection_table_columns: Get the list of columns for a table in a connection.