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

1. Open the Command Palette (CMD-SHIFT-P on Mac, CTRL+SHIFT+P on Linux/Windows).
2. 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: 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 4: 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 5: 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):

{
  "looker.instanceURL": "https://your-instance.looker.com",
  "looker.clientId": "YOUR_API_KEY_CLIENT_ID",
  "looker.clientSecret": "YOUR_API_KEY_CLIENT_SECRET",
  "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

1. Follow your IDE's documentation to open your mcp_config.json.

2. Add the following to your mcp_config.json:

   {
       "mcpServers": {
           "Looker": {
               "serverUrl": "http://127.0.0.1:5050",
               "disabledTools": [
                   "get_project_files",
                   "get_project_file",
                   "create_project_file",
                   "update_project_file",
                   "delete_project_file",
                   "run_dashboard",
                   "get_dashboards",
                   "make_dashboard",
                   "add_dashboard_filter",
                   "add_dashboard_element",
                   "get_looks",
                   "make_look",
                   "generate_embed_url",
                   "health_analyze",
                   "health_vacuum",
                   "health_pulse",
                   "query_url"
               ]
           }
       }
   }
   

   Note that here, serverUrl refers to the URL of the MCP proxy run by the extension, not the underlying MCP server.

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

Usage

1. Clone a LookML Project: Clone your LookML project's Git repository to your local machine.
2. Open the Project: Open the cloned folder in VS Code.
3. Switch Branch: Ensure you are on the desired Git branch locally. The extension will automatically switch your Looker session to this branch.
4. 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.
5. Save: Saving a file pushes the changes to Looker immediately.
6. 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:

1. 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).
2. In the dropdown menu on the right side of the Output panel, select Looker.

Changing the Log Level:

1. Open the command palette (CMD-SHIFT-P on Mac, CTRL+SHIFT+P on Windows/Linux) and select Developer: Set Log Level....
2. Select Looker from the dropdown of extensions.
3. 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.

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

1. 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).
2. When the extension starts, the proxy will listen locally on port 5050 (default: http://127.0.0.1:5050) 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.