Bigeye MCP Server

Interactúa con la plataforma de monitoreo de calidad de datos de Bigeye a través de su API Datawatch. Soporta autenticación dinámica mediante clave API.

GitHub

Documentación

Servidor MCP de Bigeye

Un servidor MCP (Model Context Protocol) que proporciona herramientas para interactuar con la plataforma Bigeye Data Observability.

Requisitos previos

Docker (Docker Desktop o Docker Engine)

Inicio rápido

Construye la imagen de Docker:
```
./build-docker.sh
```
Crea un archivo .env con tus credenciales (consulta .env.example):
```
cp .env.example .env
# Edit .env with your values
```
Inicia el contenedor de larga duración:
```
./bigeye-mcp.sh start
```
Añade el wrapper a la configuración de tu Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):
```
{
  "mcpServers": {
    "bigeye": {
      "command": "/absolute/path/to/mcp-wrapper.sh"
    }
  }
}
```
Reinicia Claude Desktop.

Cómo obtener tus credenciales

BIGEYE_API_KEY — Genérala en Bigeye en Configuración > Claves de API
BIGEYE_BASE_URL — La URL de tu instancia de Bigeye (p. ej. https://app.bigeye.com)
BIGEYE_WORKSPACE_ID — Se encuentra en tu URL de Bigeye después de /w/ (p. ej. https://app.bigeye.com/w/123/ → 123)

Variables de entorno opcionales

BIGEYE_DEBUG — Establécelo en true para un registro de depuración detallado (valor predeterminado: false)
BIGEYE_TELEMETRY — Establécelo en false para desactivar la telemetría de uso anónima (valor predeterminado: true). Consulta Telemetría.

Telemetría

Para ayudarnos a mejorar el servidor, se envían a Bigeye análisis de uso anónimos (nombre de la herramienta, duración, éxito/error). Nunca se recopilan argumentos, resultados ni datos. Establece BIGEYE_TELEMETRY=false para desactivarlo.

Modos de contenedor

Contenedor de larga duración (recomendado)

Utiliza mcp-wrapper.sh + bigeye-mcp.sh con docker compose. El contenedor permanece en ejecución y Claude Desktop se conecta mediante docker exec.

Nota: mcp-wrapper.sh depende de que Docker Compose lea automáticamente el archivo .env del directorio del proyecto. Asegúrate de que tu archivo .env esté en el mismo directorio que docker-compose.yml.

{
  "mcpServers": {
    "bigeye": {
      "command": "/absolute/path/to/mcp-wrapper.sh"
    }
  }
}

Contenedor efímero

Se crea un contenedor nuevo para cada sesión de Claude Desktop y se elimina al finalizar.

{
  "mcpServers": {
    "bigeye": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "BIGEYE_API_KEY=your_api_key_here",
        "-e", "BIGEYE_BASE_URL=https://app.bigeye.com",
        "-e", "BIGEYE_WORKSPACE_ID=your_workspace_id_here",
        "-e", "BIGEYE_DEBUG=false",
        "bigeye-mcp-server:latest"
      ]
    }
  }
}

Gestión de contenedores

El script bigeye-mcp.sh gestiona el contenedor de larga duración:

./bigeye-mcp.sh start     # Start the container
./bigeye-mcp.sh stop      # Stop the container
./bigeye-mcp.sh restart   # Restart the container
./bigeye-mcp.sh status    # Show container status
./bigeye-mcp.sh logs      # Follow container logs
./bigeye-mcp.sh rebuild   # Rebuild image and recreate container
./bigeye-mcp.sh clean     # Remove container and volumes

Configuración multi-entorno

Para conectarte a varias instancias de Bigeye (p. ej. demo y producción), crea archivos de entorno separados y anulaciones de compose:

Crea archivos de entorno para cada instancia. Ten en cuenta que las anulaciones de compose esperan nombres de variables con prefijo (BIGEYE_DEMO_* / BIGEYE_APP_*):

.env.demo:

BIGEYE_DEMO_API_KEY=your_demo_api_key
BIGEYE_DEMO_WORKSPACE_ID=your_demo_workspace_id
BIGEYE_DEBUG=false

.env.app:

BIGEYE_APP_API_KEY=your_app_api_key
BIGEYE_APP_WORKSPACE_ID=your_app_workspace_id
BIGEYE_DEBUG=false

Utiliza las anulaciones de compose específicas del entorno:

# Demo
docker compose -f docker-compose.yml -f docker-compose.demo.yml --env-file .env.demo up -d bigeye-mcp-demo

# Production
docker compose -f docker-compose.yml -f docker-compose.app.yml --env-file .env.app up -d bigeye-mcp-app

Añade ambos a la configuración de tu Claude Desktop:

{
  "mcpServers": {
    "bigeye-demo": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "BIGEYE_API_KEY=your_demo_key",
        "-e", "BIGEYE_BASE_URL=https://demo.bigeye.com",
        "-e", "BIGEYE_WORKSPACE_ID=your_demo_workspace_id",
        "bigeye-mcp-server:latest"
      ]
    },
    "bigeye-app": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "BIGEYE_API_KEY=your_app_key",
        "-e", "BIGEYE_BASE_URL=https://app.bigeye.com",
        "-e", "BIGEYE_WORKSPACE_ID=your_app_workspace_id",
        "bigeye-mcp-server:latest"
      ]
    }
  }
}

Herramientas disponibles

Gestión de incidencias

list_issues — Lista los problemas de calidad de datos en todo el espacio de trabajo (filtra por estado, esquema o assignee_ids)
get_current_user — Obtiene el usuario autenticado (id, correo electrónico, nombre, espacios de trabajo); combínalo con list_issues(assignee_ids=[id]) para encontrar problemas asignados a ti
get_issue — Obtiene los detalles completos de un único problema por su ID interno
search_issues — Encuentra problemas por su nombre/número visible (p. ej. "10921")
list_related_issues — Lista los problemas relacionados con un problema determinado mediante el linaje
list_table_issues — Lista los problemas de calidad de datos de una tabla específica por nombre
update_issue — Actualiza el estado, la prioridad de un problema o añade un mensaje a la cronología
create_incident — Crea un incidente fusionando problemas relacionados
delete_incident_members — Elimina problemas de un incidente
get_resolution_steps — Obtiene los pasos de resolución recomendados para un problema

Métricas y calidad

list_table_metrics — Lista todas las métricas (monitores) configuradas en una tabla
list_table_level_metrics — Lista los tipos de métrica que son a nivel de tabla (frente a nivel de columna)
create_metric — Crea una nueva métrica (monitor) en una tabla con validación, mapeo de enumeraciones y comprobaciones de compatibilidad de tipos de columna
get_table_profile — Obtiene el informe de perfil de datos, incluidas las estadísticas y la distribución de columnas
create_profile_job — Pone en cola un nuevo trabajo de perfilado de datos para una tabla
get_profile_job_status — Comprueba el estado de un trabajo de perfilado

Escaneo de datos sensibles

list_data_classes — Lista las categorías de clasificación de datos (p. ej., "Dirección de correo electrónico", "SSN de EE. UU.") con niveles de sensibilidad
get_scan_findings — Obtiene los resultados del escaneo de clasificación a nivel de columna que muestran dónde se detectaron datos sensibles

Catálogo de datos

search_schemas — Busca en el catálogo de datos esquemas por nombre (devuelve ids + almacén)
search_tables — Busca en el catálogo de datos tablas por nombre (devuelve ids, esquema + almacén)
search_columns — Busca en el catálogo de datos columnas por nombre (devuelve ids, tipo + tabla principal)

Linaje de datos

get_lineage_graph — Obtiene el grafo de linaje completo (ascendente/descendente/ambos) desde un nodo inicial
get_lineage_node — Obtiene los detalles de un nodo de linaje específico
list_lineage_node_issues — Lista los problemas de un nodo de linaje por su ID de nodo
search_lineage_nodes — Encuentra los ID de nodos de linaje por patrón de ruta (p. ej. "ALMACÉN/ESQUEMA/TABLA")
lineage_explore_catalog — Explora tablas en el catálogo de Bigeye
lineage_delete_node — Elimina un nodo de linaje personalizado

Análisis de causa raíz e impacto

get_upstream_root_causes — Analiza el linaje ascendente para identificar las causas raíz de los problemas
get_downstream_impact — Analiza el impacto descendente de los problemas en un nodo de linaje
get_issue_lineage_trace — Rastrea un problema de calidad de datos de principio a fin a través del linaje
list_report_upstream_issues — Lista los problemas ascendentes que afectan a un informe de BI o panel de control

Seguimiento de linaje de agentes

lineage_track_data_access — Rastrea los activos de datos a los que accede un agente de IA
lineage_commit_agent — Confirma el acceso a datos rastreado en el grafo de linaje de Bigeye
lineage_get_tracking_status — Obtiene el estado actual del seguimiento de linaje
lineage_clear_tracked_assets — Borra todos los activos de datos rastreados sin confirmar
lineage_cleanup_agent_edges — Limpia las aristas de linaje antiguas del agente de IA

Dimensiones de datos

list_dimensions — Lista todas las dimensiones de calidad de datos con sus asignaciones de tipos de métrica
get_dimension — Obtiene los detalles completos de una única dimensión por ID
create_dimension — Crea una nueva dimensión de datos
update_dimension — Actualiza el nombre o la descripción de una dimensión
delete_dimension — Elimina una dimensión de datos
get_table_dimension_coverage — Analiza las brechas de cobertura de dimensiones de una tabla (recomendado para "¿qué monitoreo falta?")
get_column_dimension_coverage — Analiza la cobertura de dimensiones de columnas específicas de una tabla

Sistema

get_health_status — Comprueba el estado y la conectividad de la API de Bigeye
list_resources — Lista todos los recursos MCP disponibles
list_data_sources — Lista todas las fuentes de datos/almacenes conectados a Bigeye

Recursos y avisos

Recursos:

bigeye://auth/status — Estado de autenticación actual
bigeye://health — Estado de salud de la API
bigeye://config — Configuración actual del servidor
bigeye://issues — Todos los problemas del espacio de trabajo configurado
bigeye://issues/active — Problemas activos con filtrado
bigeye://issues/recent — Problemas resueltos o actualizados recientemente

Avisos:

authentication_flow — Guía para configurar la autenticación
check_connection_info — Guía para verificar la conexión a la API
merge_issues_example — Ejemplos para fusionar problemas
lineage_analysis_examples — Ejemplos para el análisis de linaje

Seguimiento de linaje de agentes

El servidor incluye un seguimiento de linaje completo para agentes de IA. Usa la herramienta lineage_track_data_access para registrar los activos de datos a los que se accedió durante una sesión de agente y, luego, lineage_commit_agent para persistirlos en el grafo de linaje de Bigeye. Consulta las descripciones de las herramientas anteriores para obtener todos los detalles.

Configuración de desarrollo

Para el desarrollo local sin Docker:

Instala Python 3.12+

Crea un entorno virtual:

python -m venv venv
source venv/bin/activate

Instala las dependencias:
```
pip install -r requirements.txt
```

Establece las variables de entorno:

export BIGEYE_API_KEY="your_api_key"
export BIGEYE_BASE_URL="https://app.bigeye.com"
export BIGEYE_WORKSPACE_ID="your_workspace_id"

Ejecuta el servidor:
```
python server.py
```

Pruebas

# Run basic container tests
./scripts/test.sh

# Run basic tests + MCP protocol tests
./scripts/test.sh --mcp

# Run MCP protocol tests standalone (with optional --debug)
./scripts/test-mcp-protocol.sh

Consulta tests/README.md para obtener detalles sobre el conjunto de pruebas.

Solución de problemas

Variables de entorno faltantes

Comprueba que tu archivo .env o la configuración de Claude Desktop contengan todas las variables necesarias
Los nombres de las variables distinguen entre mayúsculas y minúsculas
Reinicia Claude Desktop después de los cambios de configuración

Errores de autenticación

Verifica que tu clave de API sea válida y tenga los permisos adecuados
El ID del espacio de trabajo debe ser un número
La URL de la instancia no debe tener una barra final

Problemas de conexión

Verifica que la URL de la instancia de Bigeye sea accesible
Comprueba la configuración del firewall/proxy
Activa el modo de depuración: BIGEYE_DEBUG=true

El contenedor no se inicia

Comprueba que Docker esté en ejecución: docker info
Verifica que la imagen exista: docker images | grep bigeye
Comprueba los registros: ./bigeye-mcp.sh logs

Directorio `~/.bigeye-mcp`

El docker-compose.yml monta ~/.bigeye-mcp en el contenedor para el almacenamiento persistente de credenciales. Docker creará este directorio automáticamente si no existe. No necesitas poner nada en él manualmente: el servidor lo usa internamente.

Bigeye MCP Server

Documentación

Servidor MCP de Bigeye

Requisitos previos

Inicio rápido

Cómo obtener tus credenciales

Variables de entorno opcionales

Telemetría

Modos de contenedor

Contenedor de larga duración (recomendado)

Contenedor efímero

Gestión de contenedores

Configuración multi-entorno

Herramientas disponibles

Gestión de incidencias

Métricas y calidad

Escaneo de datos sensibles

Catálogo de datos

Linaje de datos

Análisis de causa raíz e impacto

Seguimiento de linaje de agentes

Dimensiones de datos

Etiquetas

Sistema

Recursos y avisos

Seguimiento de linaje de agentes

Configuración de desarrollo

Pruebas

Solución de problemas

Variables de entorno faltantes

Errores de autenticación

Problemas de conexión

El contenedor no se inicia

Directorio ~/.bigeye-mcp

Directorio `~/.bigeye-mcp`