looker-mcp-skill

Looker MCP 服务技能

本技能介绍如何访问、配置和使用 Looker Model Context Protocol (MCP) Server。它支持 AI 助手、本地 IDE（VS Code、Cursor、Claude Desktop、Gemini CLI）和自动化 Agent 直接与 Looker 实例交互，以查询数据、检查语义模型、管理 LookML 项目并执行系统诊断。

---

1. 访问 Looker MCP 服务

Looker 支持两种主要的 MCP 服务部署模式：

A. Looker 托管的 MCP 服务（推荐用于 Cloud / GCP Core）

Looker 托管的 MCP 服务直接内置于 Looker 实例（Looker Core 和 Looker Original）中。它由 Google Cloud 托管和管理，无需运行独立的服务基础设施。

• 端点：https://<YOUR_LOOKER_INSTANCE_URL>/mcp
• 启用：
  1. 前往 Admin Panel > Platform > MCP。
  2. 将 Enable MCP Server 切换为 On。
  3. 确保用户和客户端应用具有相应的 API 和功能权限。

B. 本地 / 独立 MCP 服务（数据库 MCP Toolbox）

对于客户托管（本地部署）的实例、自定义开发环境或独立 CLI 集成，你可以使用 MCP Toolbox for Databases（@google/mcp-toolbox）在本地运行 MCP 服务。

• 安装 / 启动：

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

  或通过 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
  

• 环境变量：

  • LOOKER_BASE_URL：Looker 实例的基础 URL（例如，https://mycompany.looker.com）。
  • LOOKER_CLIENT_ID：Looker API 4.0 客户端 ID。
  • LOOKER_CLIENT_SECRET：Looker API 4.0 客户端密钥。
  • LOOKER_VERIFY_SSL：对于自签名开发证书，设为 false（默认值：true）。

• Cloud Run 部署： 如需在 Google Cloud Run 中运行 MCP Toolbox 服务，请参阅 Looker Cloud Run Sample。

---

2. 设置 OAuth 身份验证

要让 AI 应用和客户端代表用户安全地进行身份验证，请在 Looker 中将客户端应用注册为 OAuth 客户端。

第 1 步：注册 OAuth 客户端应用

你可以通过 API Explorer 扩展程序（推荐）或使用 curl 注册 OAuth 客户端应用。

选项 A：使用 Looker API Explorer（推荐）

Looker 安装默认包含 API Explorer 扩展程序：

1. 打开 Looker，前往 Applications > API Explorer（或访问 https://<YOUR_LOOKER_INSTANCE_URL>/extensions/marketplace_extension_api_explorer::api-explorer/）。
2. 搜索 register_oauth_client_app 端点（POST /oauth_client_apps/{client_guid}）。
3. 输入 <CLIENT_GUID>，并填写请求正文参数（client_guid、display_name、redirect_uri、enabled: true）。
4. 执行 Run Request 以注册应用。

选项 B：使用 curl

或者，向 Looker 的 oauth_client_apps 端点提交 HTTP POST 请求：

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>：为你的集成生成的唯一客户端标识符。注意：在客户端应用设置中（例如 IDE 或 AI 客户端 OAuth 配置），将 OAuth Client ID（clientId）设置为此 <CLIENT_GUID>。
• redirect_uri：接收授权码的目标回调 URL。注意：redirect_uri 会因注册的客户端或 IDE 应用而异：
  • Antigravity：https://antigravity.google/oauth-callback
  • Claude Desktop / Claude AI：https://claude.ai/api/mcp/oauth/callback 或 http://localhost:<PORT>/oauth/callback
  • VS Code / Cloud Code Extension：https://vscode.dev/redirect 或 http://127.0.0.1:<PORT>/oauth/callback
  • Cursor Desktop：https://cursor.com/mcp/callback
  • 通用 CLI / 本地工具：http://127.0.0.1:7777/oauth/callback 或 http://localhost:8080/callback

配置示例：如需客户端 OAuth 凭据和客户端 GUID 的配置步骤示例，请参阅 使用 Looker OAuth 配置 Claude Desktop。

步骤 2：执行 OAuth PKCE 流程 / Bearer 身份验证

1. 将用户重定向到授权 URL： 生成 PKCE 代码验证器和 SHA-256 挑战，然后将用户重定向到：

   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. 用授权码交换访问令牌和刷新令牌： 向令牌端点发送 POST 请求，并附上 code_verifier，以完成 PKCE 握手：

   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. 验证 MCP 请求： 在发送到 MCP 服务的请求 HTTP 标头中加入获取的 access_token：

   Authorization: Bearer <ACCESS_TOKEN>
   

---

3. 连接 MCP 客户端（IDE / Agent 配置）

将服务条目添加到客户端配置文件中（例如 .mcp.json、Cursor mcp.json 或 Gemini CLI 配置）。

远程 / 托管的 MCP 配置

原生 OAuth 客户端（例如 Claude Desktop）

原生支持 OAuth 流程的客户端在配置服务 URL 后，会自动处理授权：

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

注意：对于原生 OAuth 客户端，请使用已注册的 <CLIENT_GUID> 作为客户端 ID 配置客户端的 OAuth 设置。详情请参阅配置 Claude Desktop。

标准 HTTP 客户端 / 自定义脚本（通过标头传递 Bearer 令牌）

对于不会原生触发 OAuth 登录流程的标准 HTTP MCP 客户端或自定义脚本，请在 headers 字段中传入预先获取的身份验证令牌：

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

本地 / 独立 MCP 配置

Stdio 模式（通过 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 模式（通过 Docker 容器）

如果你通过 Docker 运行独立 MCP 服务（如第 1.B 节所述），请使用 http://localhost:5000/mcp 作为 MCP URL 连接 MCP 客户端：

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

---

4. 可通过 MCP 使用的工具

Looker MCP Server 提供 45 个工具，分为 6 个功能类别：

📊 数据与查询执行

工具	说明
query	使用 LookML 模型、探索、维度、度量、筛选条件、排序和限制来执行结构化查询。
query_sql	生成 Looker 针对给定查询定义编译出的底层 SQL 查询。
query_url	根据 Looker 可共享查询 URL 或 slug 运行或解析查询。
run_look	按 ID 执行已保存的 Look，并返回数据集结果。
run_dashboard	运行并执行指定 Dashboard ID 的元素查询。

🔍 发现与元数据目录

工具	描述
get_models	列出实例中所有可用的 LookML 模型。
get_explores	列出 LookML 模型中定义的 Explore。
get_dimensions	获取 Explore 中定义的维度字段。
get_measures	获取 Explore 中定义的度量字段。
get_filters	获取 Explore 中仅用于筛选的字段。
get_parameters	获取 Explore 中定义的参数。
get_connections	列出数据库连接配置。
get_connection_databases	列出通过某个连接可访问的数据库。
get_connection_schemas	列出数据库连接中的架构。
get_connection_tables	列出连接架构中的数据库表。
get_connection_table_columns	列出数据库表的列及其元数据。

🎨 仪表板与内容创建

工具	描述
get_looks	搜索并获取已保存的 Look。
get_dashboards	搜索并获取用户定义的仪表板和 LookML 仪表板。
make_look	根据查询定义创建新的已保存 Look。
make_dashboard	创建新的仪表板容器。
add_dashboard_element	向仪表板添加可视化或数据元素。
add_dashboard_filter	向仪表板添加动态交互式筛选器。
generate_embed_url	生成用于嵌入 Looker 内容的签名 SSO 嵌入 URL。

🛠️ LookML 项目开发

工具	描述
dev_mode	为 API 会话切换开发模式与生产模式。
get_projects	列出会话可访问的所有 LookML 项目。
get_project_directories	获取项目的目录结构树。
get_project_files	列出 LookML 项目中的文件。
get_project_file	查看特定 LookML 文件的行内容。
create_project_file	创建新的 LookML 文件（.lkml、.md 等）。
update_project_file	更新现有 LookML 文件的行内容。
delete_project_file	从项目工作区中移除 LookML 文件。
create_project_directory	在 LookML 项目中创建子目录。
delete_project_directory	删除项目子目录。
create_view_from_table	根据数据库表自动生成标准 LookML 视图定义。
validate_project	运行 LookML 验证器并返回编译错误或警告。
get_lookml_tests	获取以 LookML 编写的数据测试定义。
run_lookml_tests	执行 LookML 数据测试并返回通过或失败状态。

🌿 Git 版本控制

工具	描述
get_git_branch	获取 LookML 项目的活动 Git 分支状态。
list_git_branches	列出远程和本地 Git 分支。
create_git_branch	创建新的 Git 工作分支。
switch_git_branch	将项目会话上下文切换到指定的 Git 分支。
delete_git_branch	删除指定的 Git 分支。

⚙️ 开发者与诊断实用工具

工具	描述
health_pulse	对 Looker 实例执行轻量级存活与健康检查。
health_analyze	审查实例查询性能，并标记慢查询和 PDT 瓶颈。
health_vacuum	识别未使用的内容、未使用的 Explore 以及可供清理的候选对象。

---

5. 安全与授权指南

1. 用户范围执行与 OAuth 上下文：使用 Looker-Managed MCP Server（通过 OAuth 验证用户身份）或为独立服务配置用户专属 OAuth 令牌时，会应用用户级范围执行与访问控制（例如访问授权、模型集和用户角色）。
2. 静态 API 凭据警告：如果使用静态环境凭据（LOOKER_CLIENT_ID 和 LOOKER_CLIENT_SECRET，例如作为共享 Cloud Run 服务）部署独立/本地 MCP 服务，则所有工具执行都将在这一组 API 凭据的安全上下文中运行。这可能会绕过个人用户级访问控制和行级安全规则。
3. 开发模式隔离：编辑项目文件时，务必将 dev_mode 切换为 true，以便在暂存和提交之前，将编辑内容隔离在个人开发者工作区分支中。

---

6. 替代工具：Looker CLI（looker-cli）

对于终端工作流、Shell 脚本和 CI/CD 管道，可使用 Looker CLI（looker-cli） 这一命令行替代方案来执行 Looker API 操作。

• 代码库：Looker CLI GitHub 代码库
• 适用场景：Shell 脚本编写、终端交互式命令、CI/CD 自动化以及开发者入门工作流（参见 installing-looker-cli 和 authenticating-looker-cli 技能）。