Looker VS Code Extension

This extension provides support for LookML development in VS Code-based IDEs, including syntax highlighting, autocomplete, and file synchronization with your Looker instance.

Features

Syntax Highlighting: Rich coloring for .lkml files to make code easier to read.
LookML Validation: Syntax errors are highlighted in real-time as you type and save. Run a full validation of your project via the command palette or context menu.
Autocomplete: Context-aware suggestions for LookML parameters (explore, view, dimension, measure, etc.).
Live Synchronization: Keeps files in real-time sync with your Looker dev mode copy without needing to use Git.
Git Integration: Keeps Looker and your local Git clone in sync.
Bare Repo (Gitless) Mode: Develop LookML projects without requiring a local Git repository. Open an empty folder, populate it with project files from Looker, and enjoy full real-time file synchronization and branch mismatch detection.
Authentication: Sign in using OAuth or Looker API credentials.
Onboarding Walkthrough: Interactive UI to easily configure connection and MCP settings without manually editing settings.json.
Managed MCP Integration: Seamlessly connects to Looker's built-in Managed MCP server by default.

Getting Started

Here's how to get started with agentic LookML development in your VS Code-based editor.

Easy Setup via Onboarding Walkthrough (Recommended)

No manual settings.json editing required! The extension provides an interactive Onboarding Walkthrough that guides you through the setup process step-by-step.

Launching the Walkthrough

Open the Command Palette (CMD-SHIFT-P on Mac, CTRL+SHIFT+P on Linux/Windows).
Type and select Looker: Show Onboarding Walkthrough.

Walkthrough Steps

Step 1: Configure Connection: Enter your Looker instance URL and choose your preferred authentication method (OAuth or API key credentials).
Step 2: Select Project: Select your LookML project from the fetched list.
Step 3: Populate Workspace (for empty workspaces): If starting with an empty workspace (Bare Repo Mode), the walkthrough detects this and allows you to download and populate all LookML files directly from your remote Looker project in one click.
Step 4: MCP Server: By default, the extension uses Looker's built-in Managed MCP server (<instanceUrl>/mcp), which requires no local installation or command-line process. If you prefer to use a local or remote server, you can select the Local Server or Remote Server tab.
Step 5: Looker Skills: Installs Looker skills in your workspace to assist AI agents with LookML development. By default, skills are installed to .agents/skills. If you are using Claude agents, please select .claude/skills.
Step 6: Configure IDE MCP Client: Automatically updates your IDE's MCP configuration (mcp_config.json or .cursor/mcp.json) to connect to the extension's MCP proxy.

Optional: Manual Configuration

If you prefer to configure the extension manually instead of using the Onboarding Walkthrough, follow these steps:

1. Configure Workspace Settings

Open your workspace settings.json (Preferences: Open Workspace Settings (JSON)) and add your Looker instance and project details:

OAuth (Recommended):

OAuth is recommended because it provides a secure authorization flow without storing secrets in the editor. A Looker admin must register the Looker VS Code extension as an OAuth client in Looker's API Explorer and provide you with an OAuth client ID. The OAuth client ID is the same as the client_guid in the API Explorer. Add the following to your Workspace Settings:

{
  "looker.instanceURL": "https://your-instance.looker.com",
  "looker.oauthClientId": "YOUR_OAUTH_CLIENT_ID",
  "looker.projectId": "your_project_name"
}

Client ID & Secret (API Key):

Note: Configuring looker.clientSecret directly in settings.json is deprecated as of v1.0.0. Use the Onboarding Walkthrough to securely configure API credentials in VS Code SecretStorage.

{
  "looker.instanceURL": "https://your-instance.looker.com",
  "looker.clientId": "YOUR_API_KEY_CLIENT_ID",
  "looker.projectId": "your_project_name"
}

Note: By default, looker.mcpServerUrl is left empty to use Looker's built-in Managed MCP server (https://your-instance.looker.com/mcp).

Optional: Using Local MCP Toolbox for Databases Server

If you choose to run a local MCP server instead of Managed MCP, start the MCP Toolbox for Databases server in your terminal:

For OAuth:

LOOKER_BASE_URL="https://your-instance.looker.com" \
LOOKER_USE_CLIENT_OAUTH=true \
npx @toolbox-sdk/server --prebuilt=looker,looker-dev

For client ID & secret:

LOOKER_BASE_URL="https://your-instance.looker.com" \
LOOKER_CLIENT_ID="YOUR_CLIENT_ID" \
LOOKER_CLIENT_SECRET="YOUR_CLIENT_SECRET" \
npx @toolbox-sdk/server --prebuilt=looker,looker-dev

Then update looker.mcpServerUrl in your settings.json:

"looker.mcpServerUrl": "http://localhost:5000/mcp"

For more advanced installation and configuration options, see the official documentation.

2. Configure your IDE to connect to the extension's MCP proxy

Open or create your IDE's MCP configuration file:
- VS Code & Antigravity: <workspace>/.agents/mcp_config.json
- Cursor: <workspace>/.cursor/mcp.json
- Claude Code: <workspace>/.mcp.json

Add the following to your configuration file (shown for VS Code & Antigravity):

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

Note that here, serverUrl refers to the URL of the MCP proxy run by the extension (http://127.0.0.1:5050/mcp), not the underlying MCP server.

Note: We disable the file system tools because the extension already handles file operations.

Usage

You can develop using either Bare Repo (Gitless) Mode or Git-Backed Mode:

Option A: Bare Repo Mode (No Local Git Clone Required)

Open an Empty Folder: Open an empty workspace folder in VS Code.
Configure via Walkthrough: Open the Command Palette (CMD-SHIFT-P / CTRL+SHIFT+P) and select Looker: Show Onboarding Walkthrough, connect to your instance, and select your project.
Populate Workspace: Click Populate Workspace in the walkthrough, or run Looker: Populate Workspace from the Command Palette to download all project files from your remote Looker project.
Edit & Sync: Open and edit .lkml files. Changes synchronize in real time to your Looker developer mode copy.
Branch Awareness: The active remote Looker branch is displayed in the VS Code status bar. If the remote branch changes (e.g., switched in the Looker Web UI), the extension automatically detects the mismatch on any file open or edit and prompts you to reconcile.

Option B: Git-Backed Mode (Local Git Clone)

Clone a LookML Project: Clone your LookML project's Git repository to your local machine.
Open the Project: Open the cloned folder in VS Code.
Switch Branch: Ensure you are on the desired Git branch locally. The extension will automatically switch your Looker session to this branch.
Edit: Open a file. The extension will fetch the latest content from Looker. Be aware that this may overwrite local changes if they differ from Looker's version.
Save: Saving a file pushes the changes to Looker immediately.
Prompt the agent: Use your AI agent to assist you. For example, ask "Please add a new dimension for user_id to the users view."

Troubleshooting & Logs

If you encounter issues, you can view the extension's logs in the VS Code Output panel.

Viewing Logs:

Open the Output panel using the VS Code command palette (CMD-SHIFT-P on Mac, CTRL+SHIFT+P on Windows/Linux) and selecting View: Toggle Output. Alternatively, use the shortcut CMD-SHIFT-U (Mac) or CTRL+SHIFT+U (Windows/Linux).
In the dropdown menu on the right side of the Output panel, select Looker.

Changing the Log Level:

Open the command palette (CMD-SHIFT-P on Mac, CTRL+SHIFT+P on Windows/Linux) and select Developer: Set Log Level....
Select Looker from the dropdown of extensions.
Choose your desired logging level (e.g., Debug or Trace for more verbose output, or Info for standard output).

Support

For feedback or to report issues, please send a detailed email to our support Google Group at looker-agents-support-external@google.com.

Configuration Reference

You can configure the following settings in your workspace VS Code settings.json (or via the Settings UI under Looker):

Note: We recommend using workspace settings rather than user (global) settings because they are specific to a Looker instance and project.

Setting	Description	Default
`looker.instanceURL`	Base URL of Looker instance (e.g. `https://mycompany.looker.com`).	-
`looker.authURL`	URL for OAuth auth. Only set if different than instance URL.	`looker.instanceURL`
`looker.sdkURL`	URL for API requests. Only set if different than instance URL.	`looker.instanceURL`
`looker.oauthClientId`	Looker OAuth Client ID. Required for OAuth. Same as `client_guid`.	-
`looker.clientId`	Looker API Client ID. Required for API Key auth.	-
`looker.clientSecret`	(Deprecated) Looker API Client Secret. Use the Onboarding Walkthrough to configure API credentials in SecretStorage.	-
`looker.projectId`	Looker Project ID.	-
`looker.mcpServerUrl`	External MCP server URL. Defaults to built-in Managed MCP server (`<instanceUrl>/mcp`).	`<instanceUrl>/mcp`
`looker.acceptSelfSignedCertificates`	Ignore SSL cert errors. WARNING: insecure.	`false`
`looker.askBeforeOverwritingRemote`	Always ask before overwriting remote files on save conflict.	`false`

MCP Proxy

This VS Code extension includes a built-in proxy for the Looker MCP server (Managed MCP or Local/Remote MCP).

Why?

AI agents can act extremely fast. Because the VS Code extension syncs local changes to Looker asynchronously, a race condition can occur where the agent queries the MCP server before its file edits have been uploaded to Looker.

The built-in MCP proxy solves this by waiting for all active file syncs to complete before forwarding the agent's MCP requests to the underlying MCP server.

Configuring the Proxy

By default, the proxy automatically forwards requests to Looker's built-in Managed MCP server (<instanceUrl>/mcp). If using an external server (such as Local MCP Toolbox), set looker.mcpServerUrl to its destination URL (e.g., http://localhost:5000/mcp).
When the extension starts, the proxy will listen locally on port 5050 (default: http://127.0.0.1:5050/mcp) and forward requests to the URL defined in looker.mcpServerUrl (or the default Managed MCP URL).

Note: If port 5050 is occupied, the extension will try to run the proxy on an arbitrary available port. Check the "Looker" Output channel in VS Code for the exact proxy URL in this case.

Looker by Google Cloud

Google