Usar BigQuery con MCP, la CLI de Gemini y otros agentes

En esta guía se explica cómo usar MCP Toolbox for Databases para conectar tu proyecto de BigQuery a varios entornos de desarrollo integrado (IDEs) y herramientas para desarrolladores. Utiliza el Model Context Protocol (MCP), un protocolo abierto para conectar modelos de lenguaje grandes (LLMs) a fuentes de datos como BigQuery, lo que te permite ejecutar consultas de SQL e interactuar con tu proyecto directamente desde tus herramientas.

Si usas la CLI de Gemini, puedes usar las extensiones de BigQuery. Para saber cómo hacerlo, consulta Desarrollar con la CLI de Gemini. Si tienes previsto crear herramientas personalizadas para la CLI de Gemini, sigue leyendo.

En esta guía se muestra el proceso de conexión de los siguientes IDEs:

  • Cursor
  • Windsurf (antes Codeium)
  • Visual Studio Code (Copilot)
  • Cline (extensión de VS Code)
  • Claude para ordenadores
  • Código de Claude

Antes de empezar

  1. En la Trusted Cloud consola, en la página del selector de proyectos, selecciona o crea un Trusted Cloud by S3NS proyecto.

  2. Asegúrate de que la facturación esté habilitada en tu Trusted Cloud proyecto.

  3. Habilita la API de BigQuery en el Trusted Cloud proyecto.

  4. Configura los roles y permisos necesarios para completar esta tarea. Necesitarás el rol Usuario de BigQuery (roles/bigquery.user), el rol Lector de datos de BigQuery (roles/bigquery.dataViewer) o permisos de gestión de identidades y accesos equivalentes para conectarte al proyecto.

  5. Configura las credenciales predeterminadas de la aplicación (ADC) en tu entorno.

Instalar la caja de herramientas de MCP

No es necesario que instales MCP Toolbox si solo tienes previsto usar las extensiones de la CLI de Gemini para BigQuery, ya que incluyen las funciones de servidor necesarias. Para otros IDEs y herramientas, sigue los pasos de esta sección para instalar MCP Toolbox.

La caja de herramientas actúa como un servidor de Model Context Protocol (MCP) de código abierto que se encuentra entre tu IDE y BigQuery, lo que proporciona un plano de control seguro y eficiente para tus herramientas de IA.

  1. Descarga la versión más reciente de la caja de herramientas de MCP como archivo binario. Selecciona el binario correspondiente a tu sistema operativo y a la arquitectura de tu CPU. Debes usar la versión V0.7.0 o una posterior de MCP Toolbox:

    linux/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox

    Sustituye VERSION por la versión de MCP Toolbox (por ejemplo, v0.7.0).

    macOS darwin/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox

    Sustituye VERSION por la versión de MCP Toolbox (por ejemplo, v0.7.0).

    macOS darwin/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/amd64/toolbox

    Sustituye VERSION por la versión de MCP Toolbox (por ejemplo, v0.7.0).

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox

    Sustituye VERSION por la versión de MCP Toolbox (por ejemplo, v0.7.0).

  2. Haz que el archivo binario sea ejecutable:

    chmod +x toolbox

  3. Verifica la instalación:

    ./toolbox --version

Configurar clientes y conexiones

En esta sección se explica cómo conectar BigQuery a sus herramientas.

Si usas la CLI de Gemini independiente, no tienes que instalar ni configurar MCP Toolbox, ya que las extensiones incluyen las funciones de servidor necesarias.

En el caso de otras herramientas e IDEs compatibles con MCP, primero debes instalar MCP Toolbox.

Código de Claude

  1. Instala Claude Code.
  2. Crea un archivo .mcp.json en la raíz de tu proyecto, si no existe.
  3. Añade la configuración, sustituye las variables de entorno por tus valores y guarda los cambios: 
            {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
  4. Reinicia Claude Code para cargar los nuevos ajustes. Cuando se vuelva a abrir, la herramienta indicará que se ha detectado el servidor MCP configurado.

Claude para ordenadores

  1. Abre Claude Desktop y ve a Configuración.
  2. En la pestaña Desarrollador, haz clic en Editar configuración para abrir el archivo de configuración.
  3. Añade la configuración, sustituye las variables de entorno por tus valores y guarda los cambios: 
            {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
  4. Reinicia Claude Desktop.
  5. En la nueva pantalla de chat se muestra un icono de martillo (MCP) con el nuevo servidor MCP.

Cline

  1. Abre la extensión Cline en VS Code y toca el icono Servidores MCP.
  2. Toca Configurar servidores MCP para abrir el archivo de configuración.
  3. Añade la siguiente configuración, sustituye las variables de entorno por tus valores y guarda los cambios: 
            {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

Si el servidor se conecta correctamente, aparecerá el estado activo en verde.

Cursor

  1. Crea el directorio .cursor en la raíz de tu proyecto si no existe.
  2. Crea el archivo .cursor/mcp.json si no existe y ábrelo.
  3. Añade la siguiente configuración, sustituye las variables de entorno por tus valores y guarda los cambios: 
            {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
  4. Abre Cursor y ve a Configuración > Configuración del cursor > MCP. El estado activo verde aparece cuando el servidor se conecta.

Visual Studio Code (Copilot)

  1. Abre VS Code y crea un directorio .vscode en la raíz de tu proyecto si no existe.
  2. Crea el archivo .vscode/mcp.json si no existe y ábrelo.
  3. Añade la siguiente configuración, sustituye las variables de entorno por tus valores y guarda los cambios: 
            {
          "servers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
  4. Vuelve a cargar la ventana de VS Code. La extensión compatible con MCP detecta automáticamente la configuración e inicia el servidor.

Windsurf

  1. Abre Windsurf y ve al asistente de Cascade.
  2. Haz clic en el icono de MCP y, a continuación, en Configurar para abrir el archivo de configuración.
  3. Añade la siguiente configuración, sustituye las variables de entorno por tus valores y guarda los cambios: 
            {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

Nota: La variable de entorno BIGQUERY_PROJECT especifica el ID de proyecto predeterminado Trusted Cloud que debe usar MCP Toolbox. Todas las operaciones de BigQuery, como la ejecución de consultas, se realizan en este proyecto.

Usar las herramientas

Tu herramienta de IA ahora está conectada a BigQuery mediante MCP. Prueba a pedirle a tu asistente de IA que muestre las tablas, cree una tabla o defina y ejecute otras instrucciones de SQL.

El LLM tiene acceso a las siguientes herramientas:

  • analyze_contribution realiza un análisis de contribución, también llamado análisis de factores clave.
  • ask_data_insights realiza análisis de datos, obtiene estadísticas o responde preguntas complejas sobre el contenido de las tablas de BigQuery.
  • execute_sql ejecuta una instrucción SQL.
  • forecast: prevé datos de series temporales.
  • get_dataset_info obtiene los metadatos del conjunto de datos.
  • get_table_info obtiene los metadatos de la tabla.
  • list_dataset_ids: muestra los conjuntos de datos.
  • list_table_ids: muestra las tablas.
  • search_catalog: busca una tabla usando lenguaje natural.