SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslooker-mcp-skill

looker-mcp-skill

Agents & models

View repository

Updated 10-16 00:01

About this skill

Looker MCP Server Skill

This skill documents how to access, configure, and use the Looker Model Context Protocol (MCP) Server. It enables AI assistants, local IDEs (VS Code, Cursor, Claude Desktop, Gemini CLI), and automated agents to interact directly with Looker instances to query data, inspect semantic models, manage LookML projects, and execute system diagnostics.

1. Accessing the Looker MCP Server

Looker supports two primary deployment modes for the MCP server:

A. Looker-Managed MCP Server (Recommended for Cloud / GCP Core)

The Looker-Managed MCP Server is built directly into Looker instances (Looker Core and Looker Original). It is hosted and managed by Google Cloud, eliminating the need to run separate server infrastructure.

  • Endpoint: https://<YOUR_LOOKER_INSTANCE_URL>/mcp
  • Enablement:
    1. Navigate to Admin Panel > Platform > MCP.
    2. Toggle Enable MCP Server to On.
    3. Ensure users and client applications have appropriate API and feature permissions.

B. Local / Standalone MCP Server (MCP Toolbox for Databases)

For customer-hosted (on-premise) instances, custom developer environments, or standalone CLI integrations, you can run the MCP server locally using the MCP Toolbox for Databases (@google/mcp-toolbox).

  • Installation / Launch:

    npx @google/mcp-toolbox --prebuilt=looker,looker-dev

    Or via Docker:

    docker run -p 5000:5000 \
  -e LOOKER_BASE_URL="https://your-instance.looker.com" \
  -e LOOKER_CLIENT_ID="<CLIENT_ID>" \
  -e LOOKER_CLIENT_SECRET="<CLIENT_SECRET>" \
  us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt=looker,looker-dev --address=0.0.0.0

  • Environment Variables:

    • LOOKER_BASE_URL: Base URL of your Looker instance (e.g., https://mycompany.looker.com).
    • LOOKER_CLIENT_ID: Looker API 4.0 Client ID.
    • LOOKER_CLIENT_SECRET: Looker API 4.0 Client Secret.
    • LOOKER_VERIFY_SSL: Set to false for self-signed development certificates (default: true).

  • Cloud Run Deployment: For running the MCP Toolbox server in Google Cloud Run, refer to the Looker Cloud Run Sample.

2. Setting Up OAuth Authentication

To allow AI applications and clients to securely authenticate on behalf of users, register your client application as an OAuth client in Looker.

Step 1: Register OAuth Client Application

You can register an OAuth client application using either the API Explorer extension (recommended) or via curl.

Option A: Using the Looker API Explorer (Recommended)

The API Explorer extension is included by default in Looker installations:

  1. Open Looker and navigate to Applications > API Explorer (or go to https://<YOUR_LOOKER_INSTANCE_URL>/extensions/marketplace_extension_api_explorer::api-explorer/).
  2. Search for the register_oauth_client_app endpoint (POST /oauth_client_apps/{client_guid}).
  3. Enter your <CLIENT_GUID> and populate the request body parameters (client_guid, display_name, redirect_uri, enabled: true).
  4. Execute Run Request to register the application.

Option B: Using curl

Alternatively, submit an HTTP POST request to Looker's oauth_client_apps endpoint:

curl -X POST "https://<YOUR_LOOKER_INSTANCE_URL>/api/4.0/oauth_client_apps/<CLIENT_GUID>" \
  -H "Authorization: Bearer <ADMIN_BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_guid": "<CLIENT_GUID>",
    "display_name": "My AI Assistant Client",
    "redirect_uri": "http://127.0.0.1:7777/oauth/callback",
    "enabled": true
  }'
  • <CLIENT_GUID>: A unique client identifier generated for your integration. Note: In your client application setup (e.g., IDE or AI client OAuth config), set the OAuth Client ID (clientId) to this <CLIENT_GUID>.
  • redirect_uri: Target callback URL where authorization codes are sent. Note: The redirect_uri varies depending on the specific client or IDE application being registered:
    • Antigravity: https://antigravity.google/oauth-callback
    • Claude Desktop / Claude AI: https://claude.ai/api/mcp/oauth/callback or http://localhost:<PORT>/oauth/callback
    • VS Code / Cloud Code Extension: https://vscode.dev/redirect or http://127.0.0.1:<PORT>/oauth/callback
    • Cursor Desktop: https://cursor.com/mcp/callback
    • Generic CLI / Local Tools: http://127.0.0.1:7777/oauth/callback or http://localhost:8080/callback

Sample Configuration: For a step-by-step example of configuring client OAuth credentials and client GUIDs, see Configuring Claude Desktop with Looker OAuth.

Step 2: Perform OAuth PKCE Flow / Bearer Authentication

  1. Redirect User to Authorization URL: Generate a PKCE code verifier and SHA-256 challenge, then redirect the user to:

    https://<YOUR_LOOKER_INSTANCE_URL>/auth/oauth?client_id=<CLIENT_GUID>&response_type=code&code_challenge=<PKCE_CHALLENGE>&code_challenge_method=S256&redirect_uri=<REDIRECT_URI>

  2. Exchange Authorization Code for Access & Refresh Tokens: Send a POST request to the token endpoint including the code_verifier to complete the PKCE handshake:

    curl -X POST "https://<YOUR_LOOKER_INSTANCE_URL>/api/4.0/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<CLIENT_GUID>" \
  -d "redirect_uri=<REDIRECT_URI>" \
  -d "code=<AUTHORIZATION_CODE>" \
  -d "code_verifier=<CODE_VERIFIER>"

  3. Authenticate MCP Requests: Include the acquired access_token in the HTTP header for requests sent to the MCP server:

    Authorization: Bearer <ACCESS_TOKEN>

3. Connecting MCP Clients (IDE / Agent Configuration)

Add the server entry to your client configuration file (e.g., .mcp.json, Cursor mcp.json, or Gemini CLI config).

Remote / Managed MCP Configuration

Native OAuth Clients (e.g. Claude Desktop)

Clients that natively support OAuth flows automatically handle authorization when configured with the server URL:

{
  "mcpServers": {
    "Looker": {
      "httpUrl": "https://<YOUR_LOOKER_INSTANCE_URL>/mcp"
    }
  }
}

Note: For native OAuth clients, configure the client's OAuth settings using your registered <CLIENT_GUID> as the Client ID. See Configuring Claude Desktop for details.

Standard HTTP Clients / Custom Scripts (Bearer Token via Headers)

For standard HTTP MCP clients or custom scripts that do not natively trigger OAuth login flows, pass the pre-acquired authentication token in the headers field:

{
  "mcpServers": {
    "Looker": {
      "httpUrl": "https://<YOUR_LOOKER_INSTANCE_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

Local / Standalone MCP Configuration

Stdio Mode (via npx)

{
  "mcpServers": {
    "Looker": {
      "command": "npx",
      "args": ["-y", "@google/mcp-toolbox", "--prebuilt=looker,looker-dev"],
      "env": {
        "LOOKER_BASE_URL": "https://<YOUR_LOOKER_INSTANCE_URL>",
        "LOOKER_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "LOOKER_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>"
      }
    }
  }
}

HTTP Mode (via Docker container)

If you are running the standalone MCP server via Docker (as specified in Section 1.B), connect your MCP client using http://localhost:5000/mcp as the MCP URL:

{
  "mcpServers": {
    "Looker": {
      "httpUrl": "http://localhost:5000/mcp"
    }
  }
}

4. Tools Available via MCP

The Looker MCP Server exposes 45 tools categorized into 6 functional areas:

📊 Data & Query Execution

Tool Description
query Executes structured queries using LookML model, explore, dimensions, measures, filters, sorts, and limits.
query_sql Generates the underlying SQL query compiled by Looker for a given query definition.
query_url Runs or resolves queries given a Looker shareable query URL or slug.
run_look Executes a saved Look by ID and returns dataset results.
run_dashboard Runs and executes element queries for a specified Dashboard ID.

🔍 Discovery & Metadata Catalog

Tool Description
get_models Lists all available LookML models in the instance.
get_explores Lists Explores defined within a LookML model.
get_dimensions Retrieves dimension fields defined for an Explore.
get_measures Retrieves measure fields defined for an Explore.
get_filters Retrieves filter-only fields defined for an Explore.
get_parameters Retrieves parameters defined for an Explore.
get_connections Lists database connection configurations.
get_connection_databases Lists databases accessible via a connection.
get_connection_schemas Lists schemas inside a database connection.
get_connection_tables Lists database tables inside a connection schema.
get_connection_table_columns Lists columns and metadata for a database table.

🎨 Dashboards & Content Creation

Tool Description
get_looks Searches and retrieves saved Looks.
get_dashboards Searches and retrieves user-defined and LookML dashboards.
make_look Creates a new saved Look from a query definition.
make_dashboard Creates a new dashboard container.
add_dashboard_element Adds visualization/data elements to a dashboard.
add_dashboard_filter Adds dynamic interactive filters to a dashboard.
generate_embed_url Generates signed SSO embed URLs for embedding Looker content.

🛠️ LookML Project Development

Tool Description
dev_mode Toggles Development Mode vs Production Mode for the API session.
get_projects Lists all LookML projects accessible to the session.
get_project_directories Gets the directory structure tree of a project.
get_project_files Lists files in a LookML project.
get_project_file Views line contents of a specific LookML file.
create_project_file Creates a new LookML file (.lkml, .md, etc.).
update_project_file Updates line content of an existing LookML file.
delete_project_file Removes a LookML file from the project workspace.
create_project_directory Creates a subdirectory in the LookML project.
delete_project_directory Deletes a project subdirectory.
create_view_from_table Auto-generates standard LookML view definitions from a database table.
validate_project Runs the LookML validator and returns compilation errors/warnings.
get_lookml_tests Retrieves data test definitions written in LookML.
run_lookml_tests Executes LookML data tests and returns pass/fail status.

🌿 Git Version Control

Tool Description
get_git_branch Retrieves active Git branch status for a LookML project.
list_git_branches Lists remote and local Git branches.
create_git_branch Creates a new Git working branch.
switch_git_branch Switches project session context to specified Git branch.
delete_git_branch Deletes a specified Git branch.

⚙️ Developer & Diagnostics Utilities

Tool Description
health_pulse Performs lightweight liveness and health checks on Looker instance.
health_analyze Audits instance query performance and flags slow queries/PDT bottlenecks.
health_vacuum Identifies un-utilized content, unused Explores, and candidate objects for cleanup.

5. Security & Authorization Guidelines

  1. User Scope Enforcement & OAuth Context: User-level scope enforcement and access controls (e.g., Access Grants, Model Sets, and User Roles) apply when using the Looker-Managed MCP Server (which authenticates users via OAuth) or when a standalone server is configured with user-specific OAuth tokens.
  2. Static API Credential Warning: If the standalone/local MCP server is deployed with static environment credentials (LOOKER_CLIENT_ID and LOOKER_CLIENT_SECRET, e.g., as a shared Cloud Run service), all tool executions run under the security context of that single API credential pair. This may bypass individual user-level access controls and row-level security rules.
  3. Dev Mode Isolation: Always toggle dev_mode to true when editing project files to isolate edits to personal developer workspace branches before staging and committing.

6. Alternative Tooling: Looker CLI (looker-cli)

For terminal workflows, shell scripts, and CI/CD pipelines, Looker CLI (looker-cli) is available as a command-line alternative for interacting with Looker API operations.

  • Repository: Looker CLI GitHub Repository
  • Use Cases: Shell scripting, terminal interactive commands, CI/CD automation, and developer onboarding workflows (see installing-looker-cli and authenticating-looker-cli skills).