使用 MCP Toolbox for Databases

本页面介绍了如何使用 MCP Toolbox for Databases 将 Looker 实例连接到支持 Model Context Protocol (MCP) 的集成开发环境 (IDE) 和开发者工具。如果您使用的是客户托管型实例，或者您更喜欢自行管理基础架构，那么 MCP 工具箱是不错的选择。否则，我们建议改用 Looker 管理的 MCP 服务器。

我们建议将 Gemini CLI 的专用 Looker 扩展程序与 MCP Toolbox 搭配使用。使用 Looker 的语义层为 Gemini CLI 提供对可信数据的安全、受监管的按需访问权限，并通过自动根据自然语言提示创建报告、可视化图表和信息中心来加快工作流程。作为 Google Cloud的新一代命令行界面，Gemini CLI 是建议用于从命令行与 Looker 实例交互的工具。

您还可以使用通用型 MCP Toolbox for Databases 连接支持 Model Context Protocol (MCP) 的其他集成开发环境 (IDE) 和开发者工具。MCP Toolbox 是一款开源 MCP 服务器，可通过处理身份验证和连接池等复杂任务，简化将 AI 智能体连接到数据的过程，让您可以直接通过 IDE 使用自然语言与数据进行交互。对于这些工具，此方法可提供核心数据库互动功能。

Gemini CLI 和扩展程序简介

Gemini CLI 是一款开源 AI 智能体，旨在通过协助编码、调试、数据探索和内容创建来加速开发工作流。其使命是提供优雅的代理体验，用于与数据云服务和热门的开源数据库进行互动。

扩展程序的运作方式

Gemini CLI 具有高度可扩展性，可通过扩展程序添加新工具和功能。这些扩展程序安装起来非常简单。您可以从 GitHub 网址、本地目录或可配置的注册数据库中加载它们。这些扩展程序提供丰富的功能，包括新的工具、斜杠命令和提示，可帮助您简化工作流程。

准备 Looker 身份验证

您可以通过两种方式使用 Looker 对 MCP 客户端进行身份验证：可以使用标准 API 凭据，也可以通过 OAuth 应用注册对客户端进行身份验证。

方法 1：API 凭据

1. 获取 Looker 客户端 ID 和客户端密钥。按照 Looker API 身份验证文档页面上的说明操作。
2. 准备好 Looker 实例的基础网址。它可能类似于 https://looker.example.com。在某些情况下，API 会在其他端口上进行监听，您需要改用 https://looker.example.com:19999。

方法 2：OAuth 应用注册

1. 打开 Looker API Explorer。

   已安装 API Explorer

   如果您的 Looker 实例已安装 API 探索器，您可以使用以下网址格式访问它：

   LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/
   

   未安装 API Explorer

   如果您的 Looker 实例没有 API Explorer，您可以从 Looker Marketplace 安装它。如需了解如何安装 API Explorer，请参阅使用 API Explorer 页面。

   PSA 专用实例

   如果您使用的是采用专用服务访问通道的 Looker (Google Cloud Core) 专用连接实例，则不支持 Looker Marketplace 和 API Explorer。如需注册 AI 智能体，您必须直接调用 oauth_client_apps API 端点。如果您使用此方法，则可以跳过此 API Explorer 程序的其余步骤。

   以下是一个 curl 命令示例，您可以使用该命令通过 oauth_client_apps 端点注册代理。

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

2. 在 Auth 方法下，找到 Register OAuth App API 端点。您还可以在搜索字段中搜索“oauth 应用”。

3. 选择 Run It。

4. 对于 client_guid，请输入自定义字符串（例如 gemini_cli 或 claude-desktop）。

5. 在请求正文中，输入以下 JSON 配置：

   {
     "redirect_uri": "AI_AGENT_REDIRECT_URI",
     "display_name": "APPLICATION_NAME",
     "description": "APPLICATION_DESCRIPTION",
     "enabled": true
   }
   

   替换以下内容：

   • AI_AGENT_REDIRECT_URI：AI 智能体扩展程序或共享服务应用的重定向 URI。

     • 对于云托管的应用，它可能看起来像一个安全的 HTTPS 网址：https://AI_AGENT_URL/oauth2callback

     • 对于在本地运行的应用，它应为具有静态端口的 localhost 网址：http://localhost:7777/oauth/callback

     • 对于 IDE，它可能如下所示：vscode://google.vscode-looker-official/oauth_callback

   • APPLICATION_NAME：OAuth 应用的显示名称，例如 Claude Desktop。

   • APPLICATION_DESCRIPTION：OAuth 应用的简短说明。

6. 勾选 I understand that this API 端点 will change data 旁边的确认框，然后选择 Run。

安装 MCP Toolbox

1. 以二进制文件形式下载最新版本的 MCP Toolbox。选择与您的操作系统和 CPU 架构对应的二进制文件。您必须使用 MCP Toolbox V1.0.0 版或更高版本。

   linux/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/linux/amd64/toolbox
   
   

   darwin/arm64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/darwin/arm64/toolbox
   
   

   darwin/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/darwin/amd64/toolbox
   
   

   windows/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/windows/amd64/toolbox.exe
   
   

2. 将该二进制文件设为可执行文件。

   chmod +x toolbox
   

3. 验证安装。

   ./toolbox --version
   

将 MCP Toolbox 作为共享服务运行

对于需要通过 HTTPS 进行 OAuth 身份验证的 MCP 客户端，您必须将 MCP Toolbox 部署在 HTTPS 反向代理（例如 Cloud Run）后面。反向代理会终止 SSL 并将请求转发到 MCP Toolbox 容器。

配置服务器环境

1. 在部署中设置以下环境变量：

   • LOOKER_BASE_URL=YOUR_LOOKER_BASE_URL
   • LOOKER_USE_CLIENT_OAUTH=true

2. 使用以下实参运行 MCP Toolbox：

   • --prebuilt=looker,looker-dev
   • --mcp-prm-file=prm.json
   • [--address=0.0.0.0]
   • [--port=8080]

   MCP Toolbox 通常监听 127.0.0.1 端口 5000。如果反向代理位于其他主机上，请使用 --address=0.0.0.0 绑定到所有 IP 地址。如果您需要使用 5000 以外的监听端口，请使用 --port= 设置。例如，Cloud Run 会自动将来自端口 443（即 HTTPS 端口）的外部流量转发到 8080。

3. 创建一个具有以下结构的受保护资源元数据 (PRM) 配置文件 (prm.json)：

   {
   "resource": "https://PROXY_URL/mcp",
   "authorization_servers": ["LOOKER_URL"],
   "scopes_supported": ["cors_api"]
   }
   

   替换以下内容：

   • PROXY_URL：反向代理服务器的网域和基本路径。
   • LOOKER_URL：Looker 实例的基础网址。

如需查看有关在将 MCP Toolbox 作为共享服务运行时如何配置客户端的示例，请参阅 Claude 桌面配置示例。

配置 MCP 客户端

本部分介绍了如何配置各种开发者工具，以便使用 MCP Toolbox for Databases 连接到 Looker 实例。该工具箱充当位于 IDE 和数据库之间的开源 Model Context Protocol (MCP) 服务器，为 AI 工具提供安全高效的控制平面。选择特定工具的标签页，以查看配置说明。

• Gemini CLI
• Gemini Code Assist
• Claude code
• Claude Desktop
• Cline（VS Code 扩展程序）
• Cursor
• Visual Studio Code (Copilot)
• Windsurf (Codium)

      {
        "mcpServers": {
          "looker-toolbox": {
            "command": "./PATH/TO/toolbox",
            "args": ["--stdio", "--prebuilt", "looker"],
            "env": {
                "LOOKER_BASE_URL": "LOOKER_URL",
                "LOOKER_CLIENT_ID": "CLIENT_ID",
                "LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
                "LOOKER_VERIFY_SSL": "VERIFY_SSL",
          }
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "command": "./PATH/TO/toolbox",
            "args": ["--stdio", "--prebuilt", "looker"],
            "env": {
                "LOOKER_BASE_URL": "LOOKER_URL",
                "LOOKER_CLIENT_ID": "CLIENT_ID",
                "LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
                "LOOKER_VERIFY_SSL": "VERIFY_SSL",
          }
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "command": "./PATH/TO/toolbox",
            "args": ["--stdio", "--prebuilt", "looker"],
            "env": {
                "LOOKER_BASE_URL": "LOOKER_URL",
                "LOOKER_CLIENT_ID": "CLIENT_ID",
                "LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
                "LOOKER_VERIFY_SSL": "VERIFY_SSL",
          }
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "command": "./PATH/TO/toolbox",
            "args": ["--stdio", "--prebuilt", "looker"],
            "env": {
                "LOOKER_BASE_URL": "LOOKER_URL",
                "LOOKER_CLIENT_ID": "CLIENT_ID",
                "LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
                "LOOKER_VERIFY_SSL": "VERIFY_SSL",
          }
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

      {
        "servers": {
          "looker-toolbox": {
            "command": "./PATH/TO/toolbox",
            "args": ["--stdio", "--prebuilt", "looker"],
            "env": {
                "LOOKER_BASE_URL": "LOOKER_URL",
                "LOOKER_CLIENT_ID": "CLIENT_ID",
                "LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
                "LOOKER_VERIFY_SSL": "VERIFY_SSL",
          }
          }
        }
      }
  

      {
        "servers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "command": "./PATH/TO/toolbox",
            "args": ["--stdio", "--prebuilt", "looker"],
            "env": {
                "LOOKER_BASE_URL": "LOOKER_URL",
                "LOOKER_CLIENT_ID": "CLIENT_ID",
                "LOOKER_CLIENT_SECRET": "CLIENT_SECRET",
                "LOOKER_VERIFY_SSL": "VERIFY_SSL",
          }
          }
        }
      }
  

      {
        "mcpServers": {
          "looker-toolbox": {
            "type": "http",
            "url": "https://PROXY_URL/mcp"
          }
        }
      }
  

使用 AI 工具

您的 AI 工具现在已使用 MCP 连接到 Looker。尝试让 AI 助理列出模型、探索、维度和度量。您还可以通过检索查询的 SQL 或运行已保存的 Look 来运行查询。

LLM 可使用以下工具：

Looker 模型和查询工具

这些工具用于获取 Looker 模型的相关信息，并针对该模型执行查询。

• get_models：列出 Looker 实例上的所有 LookML 模型。
• get_explores：列出给定模型中的探索。
• get_dimensions：列出指定探索中的维度。
• get_measures：列出指定探索中的度量。
• get_filters：列出指定探索中的过滤条件。
• get_parameters：列出指定探索中的参数。
• query：运行查询并返回数据。
• query_sql：返回 Looker 为查询生成的 SQL。
• query_url：返回指向 Looker 中查询的链接，以便进一步探索。

Looker 内容工具

这些工具会从 Looker 实例中获取已保存的内容（Look 和信息中心），并创建新的已保存内容。

• get_looks：返回与指定标题或说明匹配的已保存的 Look。
• run_look：运行已保存的 Look 并返回数据。
• make_look：在 Looker 中创建已保存的 Look 并返回网址。
• get_dashboards：返回与指定标题或说明匹配的已保存信息中心。
• make_dashboard：在 Looker 中创建已保存的信息中心并返回网址。
• add_dashboard_element：向信息中心添加图块。

Looker 实例健康状况工具

这些工具提供的健康检查算法与热门 CLI Henry 提供的算法相同。

• health_pulse：检查 Looker 实例的运行状况。
• health_analyze：分析 Looker 对象的使用情况。
• health_vacuum：查找可能未使用的 LookML 元素。

LookML 编写工具

这些工具可让调用方编写和修改 LookML 文件，并获取有效编写 LookML 所需的数据库架构。

• dev_mode：为会话开启和关闭开发模式。LookML 撰写必须在开发模式下完成。在开发模式下运行的查询会使用修改后的 LookML，因此您可以测试更改的影响。
• get_projects：获取可用 LookML 项目的列表。
• get_project_files：获取项目中的 LookML 文件列表。
• get_project_file：获取 LookML 文件的内容。
• create_project_file：创建新的 LookML 文件。
• update_project_file：修改现有 LookML 文件。
• delete_project_file：删除 LookML 文件。
• get_connections：获取连接列表。
• get_connection_schemas：获取连接的架构列表。
• get_connection_databases：获取连接的数据库列表。
• get_connection_tables：获取连接的表列表。
• get_connection_table_columns：获取连接中表的列列表。