Looker 管理的 MCP 服务器

Looker 管理的 MCP 服务器是一种内置集成，可将 Model Context Protocol (MCP) 服务器直接嵌入 Looker 平台。它允许 AI 智能体（例如 Gemini CLI、Claude Desktop、Cursor 和 Copilot）安全地连接到 Looker 实例，并与商家数据和 LookML 模型进行交互。

通过托管服务器，Looker 让您无需部署和维护自己的中间件基础设施，从而提供一个即插即用、安全且受管控的网关，让您能够获取可信的业务洞见。

如果您使用的是客户托管的实例，或者您更愿意管理自己的基础设施，则可以使用独立的 MCP Toolbox for Databases 进行连接。MCP Toolbox 是一款开源 MCP 服务器，您可以在本地计算机或自己的服务器上运行，充当 AI 智能体与 Looker 实例之间的桥梁。如需了解详情，请参阅将 Looker 与 MCP、Gemini CLI 和其他代理搭配使用文档页面。

准备工作

如需使用 Looker 管理的 MCP 服务器，您必须满足以下要求：

实例要求

• 您必须使用 Looker (Google Cloud Core) 或 Looker（原始版本）实例。
• 实例必须由 Looker 托管。

所需权限

• 如需管理工具访问权限：您必须拥有管理员 Looker 角色。
• 将 AI 智能体注册或启用为 OAuth 客户端：您必须拥有 Admin Looker 角色。
• 如需将 AI 智能体连接到 Looker 管理的 MCP 服务器：您需要使用标准 Looker 登录凭证在 OAuth 连接过程中进行身份验证。AI 智能体必须先由 Looker 管理员注册为 OAuth 客户端。连接后，AI 智能体将继承已通过身份验证的用户的 Looker 角色和访问权限。

设置代管式 MCP 服务器

配置工具访问权限，以设置代管式 MCP 服务器。

配置工具设置

默认情况下，托管式 MCP 服务器的所有工具均处于停用状态。Looker 管理员必须明确启用 AI 智能体可以使用的工具。如需了解启用工具的步骤，请参阅管理员设置 - Model Context Protocol (MCP) 文档页面。

配置 CORS 设置

如果 MCP 客户端直接在网络浏览器中运行，并且希望使用 CORS 与 Looker 管理的 MCP 服务器通信，则 Looker 管理员必须在管理控制台中将该客户端网站的网域添加到嵌入式网域许可清单。

通过 OAuth 注册 AI 智能体

如需将 AI 智能体连接到 Looker 管理的 MCP 服务器，管理员必须在 Looker 管理控制台面板中的管理 OAuth 客户端页面上，将 AI 智能体启用或注册为 OAuth 客户端应用。

您可以在应用库中启用预配置的 AI 客户端，也可以在自定义客户端标签页中注册自定义客户端：

• 应用库（推荐）：使用预配置的、由 Looker 管理的 OAuth 客户端注册，适用于热门 AI 智能体和开发者工具，例如 Cursor、VS Code、Claude Code、Claude Desktop、ChatGPT、Gemini CLI、Cline、Windsurf、Antigravity 和 Looker Extension for VS Code。
• 自定义客户端：如果您的 AI 工具未在应用库中提供，或者您需要配置自定义重定向 URI 或端口，请注册新的自定义 OAuth 客户端。

选项 1：从应用库中启用预配置的 AI 智能体

我们建议您先查看应用库标签页。

如需启用预配置的 AI 智能体客户端，请按以下步骤操作：

1. 在 Looker 管理控制台中，前往身份验证部分，然后选择管理 OAuth 客户端。
2. 选择应用库标签页。
3. 找到 AI 智能体的客户端应用（例如 Cursor、Claude Code、Cline 或 Gemini CLI）。您可以使用搜索栏按名称进行过滤。
4. 将启用开关切换到开启。
5. 复制客户端所在行中显示的客户端 ID。在配置 AI 智能体的 MCP 设置时（例如，在 mcp.json 或启动标志中），您需要提供此客户端 ID。如果未获授 Looker Admin 角色的 Looker 用户需要使用此客户端，请向他们分发客户端 ID。

重定向 URI 和动态端口处理

Looker 要求 OAuth 重定向 URI 与注册值完全匹配，并且不支持通配符重定向 URI。某些 AI 工具（例如 Claude Code 或 Cline）在发起 OAuth 回调时，默认会使用动态或临时本地端口。为了适应这些工具，Looker 会为每个库客户端预注册一个固定的默认端口（例如，Claude Code 和 Cline 使用端口 8080，Gemini CLI 使用端口 7777）。

如需将预配置的库客户端与动态端口搭配使用，请选择以下选项之一：

• 将客户端配置为使用预注册的静态端口：在工具的设置或启动命令中，指定预注册的端口。例如：
  • Claude Code：使用 --callback-port 8080 标志运行 Claude Code（或在 mcp.json 中配置 "callbackPort": 8080）。
  • Cline：将 OAuth 回调端口配置为 8080。
  • Gemini CLI：设置环境变量 export OAUTH_CALLBACK_PORT=7777。
  • VS Code：使用预注册的静态 URI http://127.0.0.1:33418/。
• 注册自定义客户端：如果您需要使用其他端口或自定义回调网址，请使用首选重定向 URI 注册自定义客户端，如下一部分所述。

方法 2：注册自定义 AI 智能体客户端

如果您的 AI 智能体未包含在应用库中，或者您需要使用自定义回调网址或端口，请按照“管理员设置 - 管理 OAuth 客户端”文档中的步骤注册自定义客户端。添加客户端后，复制客户端 ID，以便在配置 MCP 客户端时使用。

程序化注册（API Explorer 或 API）

对于自动化部署（例如 CI/CD 流水线或预配脚本），Looker 管理员可以通过编程方式注册 OAuth 客户端。

展开此部分，了解如何使用 API 或 API Explorer 注册 OAuth 客户端。

您可以使用 curl 直接通过 oauth_client_apps API 端点注册 AI 智能体：

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

或者，您也可以使用 Looker API Explorer：

1. 在身份验证方法下，找到注册 OAuth 应用 API 端点。
2. 点击运行，输入 CLIENT_GUID、redirect_uri、display_name 和 description，选中确认复选框，然后点击运行。
   • Gemini CLI

     http://localhost:7777/oauth/callback
     

     注意：某些工具（例如 Gemini CLI）可能需要您设置环境变量（例如 export OAUTH_CALLBACK_PORT=7777），以确保这些工具使用与您注册的重定向 URI 匹配的静态端口。

   • Gemini Code Assist

     http://localhost:7777/oauth/callback
     

     我们建议将 Gemini CLI 与 Gemini Code Assist 搭配使用，这样它们将共享相同的本地回调服务器和端口配置。

   • Gemini Enterprise

     https://vertexaisearch.cloud.google.com/oauth-redirect
     

   • Claude Code

     Claude Code 会使用随机可用端口进行 OAuth 回调，但您应使用 --callback-port 8080 标志（或 mcp.json 中的 callbackPort 设置）来修正此问题，使其与您注册的 URI 匹配。

     http://localhost:8080/callback
     

   • VS Code

     对于 VS Code，请使用以下 URI。

     http://127.0.0.1:33418/
     

     注意：URI 末尾的尾随斜杠 (/) 是必需的。

   • 云托管应用

     对于云托管应用，它可能类似于安全的 HTTPS 网址：

     https://AI_AGENT_URL/oauth2callback
     

   • 本地应用

     对于在本地运行的应用，重定向 URI 应为具有静态端口的 localhost 网址：

     http://localhost:7777/oauth/callback
     

     注意：某些工具（例如 Gemini CLI）可能需要您设置环境变量（例如 export OAUTH_CALLBACK_PORT=7777），以确保这些工具使用与您注册的重定向 URI 匹配的静态端口。
3. 如需验证注册，请使用您的 CLIENT_GUID 运行获取 OAuth 客户端应用端点。

配置 MCP 客户端

注册 AI 智能体后，您可以将其作为 MCP 客户端连接到代管式 MCP 端点。请参阅代理的文档，完成客户端设置。

• 服务器网址： LOOKER_INSTANCE_URL/mcp
• 身份验证：OAuth 2.1

配置示例 (mcp.json)

本部分介绍了如何配置各种开发者工具，以便使用 Looker 管理的 MCP 服务器连接到 Looker 实例。MCP 服务器位于 IDE 和 Looker 之间，为 AI 工具提供安全高效的控制平面。选择特定工具的标签页，以查看配置说明。

Gemini CLI

将 Gemini CLI 配置为直接连接到 Looker 管理的 MCP 服务器。

1. 安装 Gemini CLI。
2. 使用以下命令添加远程 MCP 服务器，并将 LOOKER_INSTANCE_URL 替换为您的 Looker 实例网址：

   gemini mcp add --transport http looker LOOKER_INSTANCE_URL/mcp
   

   或者，您也可以手动进行配置，只需将以下配置添加到 settings.json 文件（位于 ~/.gemini/settings.json 或项目目录中）即可：

   {
     "mcpServers": {
       "looker": {
         "httpUrl": "LOOKER_INSTANCE_URL/mcp",
         "oauth": {
           "clientId": "CLIENT_GUID"
         }
       }
     }
   }
   

3. 以互动模式启动 Gemini CLI：

   gemini
   

   当系统提示您连接时，CLI 会启动 OAuth 授权流程，以便安全地向您的 Looker 实例进行身份验证。

Gemini Code Assist

我们建议您将 Gemini Code Assist 配置为使用 Gemini CLI。这样就无需手动配置 MCP 服务器。

1. 确保您已安装并配置 Gemini CLI 和 Looker 管理的 MCP 服务器。
2. 配置 Gemini Code Assist 以使用 Gemini CLI。
3. 直接在 Gemini Code Assist 对话中使用自然语言开始与 Looker 实例互动。

Gemini Enterprise

将 Gemini Enterprise 配置为连接到 Looker 管理的 MCP 服务器，作为自定义 MCP 服务器数据存储区。

1. 按照官方文档中的说明，在 Gemini Enterprise 中创建自定义 MCP 服务器数据存储区。
2. 对于数据存储区配置，请使用以下值，并将 LOOKER_INSTANCE_URL 替换为您的 Looker 实例网址，将 CLIENT_GUID 替换为您在注册 OAuth 应用期间使用的确切字符串：

   {
     "instance_uri": "LOOKER_INSTANCE_URL/mcp",
     "auth_uri": "LOOKER_INSTANCE_URL/auth",
     "auth_uri_params": "&response_type=code&code_challenge_method=S256",
     "token_uri": "LOOKER_INSTANCE_URL/api/token",
     "client_id": "CLIENT_GUID",
     "client_secret": "none",
     "scopes": "cors_api",
     "pkce_support_enabled": "true"
   }
   

   PKCE 不需要 OAuth 客户端密钥，但 Gemini Enterprise 要求在 client_secret 字段中输入一个值。您可以输入 none，如示例配置中所示。

3. 请通过 OAuth 进行身份验证，以便继续操作。
4. 设置 MCP 服务器说明，帮助 Gemini 了解何时调用该服务器。例如：

   Looker Agent with API access to various aspects of Looker. Primarily used to fetch data and run dashboards from Looker.
   

5. 定义 MCP 服务器代理指令。例如：

   Use this server exclusively to interact with the Looker instance for monitoring health, checking status, and retrieving data.
   Invoke the Looker MCP server for the following request categories:
     - Instance Health Checks: Auditing connection status, uptime, performance metrics, or system errors.
     - Analytics Queries & Data Retrieval: Fetching live business metrics from Explores, Looks, or Dashboards.
   Strict Constraints:
     - No Local Estimation: Do not guess. Always fetch real-time data via MCP tools.
     - Fallback Behavior: Inform the user of connectivity failures immediately.
   

6. 前往您刚刚创建的自定义 MCP 数据存储区中的操作标签页，然后启用您希望 Gemini Enterprise 使用的工具。
   注意：虽然您还必须在 Looker 管理员设置中启用工具，但此步骤是 Gemini Enterprise 发现和使用 MCP 工具的必要步骤。
7. 最后，前往 Gemini Enterprise，点击连接器图标，然后授权 MCP 服务器，完成设置。

Claude Code

1. 安装 Claude Code。
2. 在项目根目录中创建 .mcp.json 目录（如果尚不存在）。
3. 添加以下配置，将 LOOKER_INSTANCE_URL 替换为 Looker 实例的网址，将 CLIENT_GUID 替换为 OAuth 客户端 GUID，然后保存。

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "LOOKER_INSTANCE_URL/mcp",
            "oauth": {
              "clientId": "CLIENT_GUID",
              "callbackPort": 8080
            }
          }
        }
      }
  

Claude Desktop

1. 在 Claude 桌面版中，前往设置，然后选择连接器。
2. 选择添加自定义连接器，然后输入名称（例如 Looker）。
3. 对于网址，请输入 Looker 实例的网址，并附加 /mcp 路径（例如 https://looker.example.com/mcp）。
4. 在高级设置下，输入您在 OAuth 应用注册期间为 CLIENT_GUID 使用的确切字符串。将 OAuth 客户端密钥留空。
5. 选择添加以保存连接器。当系统提示连接时，Claude 桌面版会通过浏览器安全地启动 PKCE 授权流程。

4. 重启 Claude Desktop。

Cline

1. 在 IDE 中打开 Cline 扩展程序，然后点击 MCP 服务器图标。
2. 点击配置 MCP 服务器以打开配置文件。
3. 添加以下配置，将 LOOKER_INSTANCE_URL 替换为您的 Looker 网址，然后保存。

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "LOOKER_INSTANCE_URL/mcp"
          }
        }
      }
  

服务器成功连接后，系统会显示绿色的活跃状态。

光标

1. 在项目根目录中创建 .cursor 目录（如果尚不存在）。
2. 创建 .cursor/mcp.json 文件（如果尚不存在）并打开该文件。
3. 添加以下配置，将 LOOKER_INSTANCE_URL 替换为您的 Looker 网址，然后保存。

      {
        "mcpServers": {
          "looker": {
            "url": "LOOKER_INSTANCE_URL/mcp",
            auth: {
              "CLIENT_ID": "CLIENT_GUID"
            }
          }
        }
      }
  

4. 打开 Cursor，然后依次前往设置 > Cursor 设置 > MCP。服务器连接时，系统会显示绿色的活跃状态。

Visual Studio Code (Copilot)

1. 打开 VS Code，并在项目根目录中创建 .vscode 目录（如果尚不存在）。
2. 创建 .vscode/mcp.json 文件（如果尚不存在）并打开该文件。
3. 添加以下配置，将 LOOKER_INSTANCE_URL 替换为 Looker 实例的网址，然后保存。

      {
        "servers": {
          "looker": {
            "type": "http",
            "url": "LOOKER_INSTANCE_URL/mcp"
          }
        }
      }
  

Windsurf

1. 打开 Windsurf 并前往 Cascade 助理。
2. 点击 MCP 图标，然后点击配置以打开配置文件。
3. 添加以下配置，将 LOOKER_INSTANCE_URL 替换为 Looker 实例的网址，然后保存。

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "LOOKER_INSTANCE_URL/mcp"
          }
        }
      }
  

使用客户端进行身份验证

使用 mcp.json 设置配置 MCP 客户端后，当您首次尝试通过该客户端与 Looker 交互时，系统会启动 OAuth 2.1 身份验证流程。这通常需要客户端打开一个浏览器窗口，您必须在其中使用标准凭据登录 Looker 实例，并授予应用代表您访问 Looker 的权限。

此登录流程是交互式身份验证步骤，可让 MCP 客户端获取访问令牌，以便在未来发出请求。

如需了解详情，请参阅客户端的文档。

连接后，客户端将继承您的 Looker 角色和内容访问权限。客户端还可以访问 Looker 管理员为 MCP 服务器启用的 AI 工具。如需查看所有可能工具的列表，请参阅使用 AI 工具文档。

提示： 您必须将客户端重新连接到 MCP 服务器，才能注册已启用的任何新工具。如需了解如何重新连接，请参阅客户端的文档。

安全和治理

托管式 MCP 服务器旨在继承 Looker 现有的安全和治理框架。

• 权限边界：服务器会强制执行严格的用户级权限。AI 智能体无法访问经过身份验证的用户无权查看的数据或模型。
• VPC Service Controls：对于使用 VPC Service Controls 的 Looker (Google Cloud Core) 实例，托管式 MCP 端点会遵循现有的 VPC Service Controls 边界，无需额外的政策或配置。
• 客户管理的加密密钥 (CMEK)：对于使用 CMEK 的 Looker (Google Cloud Core) 实例，托管式 MCP 服务器符合 CMEK 要求，无需额外的政策或配置。
• IP 许可清单：对于在 Looker (Google Cloud Core) 或 Looker（原始版）中使用 IP 许可清单的实例，托管式 MCP 端点会遵循现有的 IP 许可清单规则，无需任何额外配置。

审核日志记录

AI 智能体执行的每项操作都会记录在 Looker 系统活动和 Cloud Audit Logs 中。

系统活动

Looker 托管的 MCP 服务器活动会在历史记录和事件属性探索中进行跟踪。使用系统活动探索监控 Looker 使用情况文档页面提供了以下示例查询：

• Looker 管理的 MCP 服务器发起了哪些 API 调用？
• 哪些事件与来自 Looker 托管式 MCP 服务器的请求相关？
• Looker 管理员对 Looker 管理的 MCP 服务器工具设置进行了哪些更新？
• Looker 托管的 MCP 服务器的用户运行了哪些查询？

Cloud Audit Logs

Looker (Google Cloud Core) 实例还会通过 Cloud Audit Logs 跟踪 Looker 管理的 MCP 服务器活动。Looker (Google Cloud Core) 审核日志记录文档页面提供了示例查询。

限制

• 精细范围：托管式 MCP 服务器尚不支持 OAuth 范围。访问权限控制取决于全局工具许可清单和用户的基本权限。
• 动态注册：预览版不支持动态客户端注册。
• 客户端刷新：对工具许可清单的更改不会自动推送到已连接的客户端。用户在更改工具列表后必须等待 30 秒，然后重新连接客户端以刷新工具清单。如需了解如何重新连接到 MCP 服务器，请参阅客户端文档。
• 服务器容量：在预览阶段，托管式 MCP 服务器配置了固定容量，以帮助我们收集性能数据。在用量高峰期，您可能会偶尔遇到超时。这是预期行为。

价格和配额

Looker 托管的 MCP 服务器可免费使用。不过，AI 智能体发出的工具调用会消耗实例的标准管理和基于查询的 API 配额。智能体活动频繁可能会影响您的可用 API 配额。