looker-mcp-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>

1. 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>"

1. 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

🔍 Discovery & Metadata Catalog

🎨 Dashboards & Content Creation

🛠️ LookML Project Development

🌿 Git Version Control

⚙️ Developer & Diagnostics Utilities

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).