Snow Leopard BigQuery MCP

Interactúa con bases de datos de Google BigQuery mediante consultas en lenguaje natural y exploración de esquemas.

Documentación

Snow Leopard BigQuery MCP

Un servidor del Model Context Protocol (MCP) para Google BigQuery que permite a los agentes de IA interactuar con bases de datos de BigQuery mediante consultas en lenguaje natural y exploración de esquemas.

Este proyecto fue desarrollado por Snow Leopard AI como una herramienta de evaluación comparativa para nuestra plataforma, y lo ponemos a disposición del público para que la comunidad lo use y lo amplíe.

¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar abierto que permite a las aplicaciones de IA conectarse de forma segura a fuentes de datos y herramientas externas. Este servidor MCP de BigQuery actúa como un puente entre los agentes de IA y tus conjuntos de datos de BigQuery.

Características del servidor Snow Leopard BigQuery MCP

Recursos

URI del recurso	Descripción
`bigquery://tables`	Lista todas las tablas disponibles para el agente
`bigquery://tables/{table}/schema`	Obtiene el esquema de una tabla específica

Herramientas

Herramienta	Descripción
`list_tables(table: str)` (opcional)	Lista las tablas disponibles
`get_schema(table: str)` (opcional)	Obtiene el esquema de una tabla dada
`query(sql: str)`	Ejecuta SQL de BigQuery y devuelve los resultados

Inicio rápido: Claude Desktop

Requisitos previos

Antes de comenzar, asegúrate de tener:

Claude Desktop: Descargar aquí
Proyecto de Google Cloud con BigQuery habilitado: Guía de configuración
CLI de Google Cloud (gcloud): Guía de instalación
Administrador de paquetes UV: Guía de instalación

1. Configurar Google Cloud

Primero, necesitamos autenticarnos con Google.

gcloud auth application-default login

Esto abre tu navegador para autenticar tu máquina local con Google Cloud.

2. Configurar Claude Desktop

Edita tu archivo claude_desktop_config.json para agregar el servidor MCP de BigQuery.

Aplicación: Claude > Configuración > Desarrollador > Editar configuración
Mac: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Deberás configurar tu proyecto como un proyecto de Google Cloud con permisos para enviar trabajos de BigQuery. Si no tienes un proyecto en el que puedas ejecutar trabajos de BigQuery, crea y prueba uno siguiendo la Guía de inicio rápido de BigQuery de Google. Crea un proyecto y sigue las instrucciones para consultar un conjunto de datos público.

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "sl-bigquery-mcp", 
        "--dataset",
        "bigquery-public-data.usa_names",
        "--project",
        "🚨 <projectName> 🚨"
      ]
    }
  }
}

3. Cierra Claude Desktop y ábrelo desde la terminal

Dependiendo de cómo hayas instalado uv, el ejecutable uvx puede no estar en el PATH de Claude Desktop si se inicia desde la interfaz gráfica. Para asegurarte de que uvx sea accesible desde Claude Desktop, ejecútalo en la terminal.

open -a claude

Después de guardar la configuración, reinicia Claude Desktop. ¡Ahora deberías poder hacer preguntas a Claude sobre tus datos de BigQuery!

Consulta de ejemplo

What are the top 10 most popular names in 2020?

Opciones de configuración

Para ver una lista completa de parámetros:

uvx sl-bigquery-mcp --help

Usage: sl-bigquery-mcp [OPTIONS]

╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --mode                       [stdio|sse|streamable-http]  MCP transport protocol [default: stdio]                                                     │
│ --dataset                    TEXT                         Dataset(s) for mcp resources. Will create resources for all tables.                         │
│ --table                      TEXT                         Table(s) for mcp resources. Can be specified as project.dataset.table or dataset.table      │
│ --enable-list-tables-tool    --no-enable-list-tables-tool Registers list_resources tool [default: enable-list-tables-tool]                            │
│ --enable-schema-tool         --no-enable-schema-tool      Registers get_schema tool [default: enable-schema-tool]                                     │
│ --project                    TEXT                         BigQuery project [env var: BQ_PROJECT] [default: None]                                      │
│ --api-method                 [INSERT|QUERY]               BigQuery client api_method [default: QUERY]                                                 │
│ --port                       INTEGER                      [default: 8000]                                                                             │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Solución de problemas / Preguntas frecuentes

Se ha producido un error de MCP

Primero, revisa los registros de la aplicación Claude Desktop (en el mismo directorio que el archivo de configuración) para obtener errores o registros más detallados.

Al iniciar

Esto generalmente significa que Claude tiene problemas para iniciar el servidor MCP. Frecuentemente se debe a que uvx no es accesible desde la aplicación. En este caso, usa la ruta completa a tu ejecutable uvx en lugar de solo uvx en claude_desktop_config.json.

Para encontrar tu ejecutable uv, ejecuta

which uvx

De lo contrario, esto puede deberse a argumentos incorrectos, incompatibilidades de versiones de dependencias o errores. Si te encuentras con los dos últimos, por favor reporta un problema describiendo el error.

Al usar recursos / herramientas

Esto puede ser una configuración incorrecta del servidor MCP, problemas de autenticación, el LLM recibiendo demasiados datos o, por supuesto, errores del producto. Después de revisar los registros, considera usar el Inspector MCP para depurar tu problema. Y, por supuesto, reporta cualquier error que encuentres en nuestro tablero de problemas.

Desarrollo y pruebas locales

Configurar el entorno de desarrollo

Clona el repositorio
Configura el entorno virtual e instala las dependencias
Verifica la instalación

git clone https://github.com/SnowLeopard-AI/bigquery-mcp.git
cd bigquery-mcp

uv sync
source .venv/bin/activate

sl-bigquery-mcp --help

Autenticarse con Google Cloud

El siguiente comando abrirá un navegador para que inicies sesión en tu cuenta de Google Cloud. Debes tener un proyecto de Google Cloud con BigQuery habilitado. Si no lo tienes, consulta la guía de configuración de BigQuery de Google.

gcloud auth application-default login
gcloud config set project <projectName>
gcloud auth application-default set-quota-project <projectName>

Ejecutar pruebas

Ejecuta las pruebas para asegurarte de que tu entorno de desarrollo esté configurado correctamente.

pytest tests

Nota: las pruebas ejecutan consultas reales de BigQuery contra conjuntos de datos públicos y requieren autenticación.

Inspector MCP local

Para pruebas prácticas y desarrollo, usa la herramienta Inspector MCP:

npx @modelcontextprotocol/inspector uv run sl-bigquery-mcp --dataset bigquery-public-data.usa_names

Contribuciones

¡Agradecemos las contribuciones! Por favor, coordina con nosotros en discord para asegurar que tus cambios puedan incorporarse rápidamente al repositorio. Comunicarse antes de programar siempre ahorra tiempo.

Para la logística de contribuir a un proyecto de código abierto, consulta el repositorio de primeras contribuciones.

Soporte

Problemas: Problemas de GitHub
Documentación: Documentación de BigQuery
Protocolo MCP: Model Context Protocol
Contacto: Servidor de Discord