Bigeye MCP Server

Interaja com a plataforma de monitoramento de qualidade de dados da Bigeye por meio de sua API Datawatch. Suporta autenticação dinâmica por chave de API.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Bigeye

Um servidor MCP (Model Context Protocol) que fornece ferramentas para interagir com a plataforma de Observabilidade de Dados Bigeye.

Pré-requisitos

  • Docker (Docker Desktop ou Docker Engine)

Início Rápido

  1. Construa a imagem Docker:

    ./build-docker.sh

  2. Crie um arquivo .env com suas credenciais (veja .env.example):

    cp .env.example .env
# Edit .env with your values

  3. Inicie o contêiner de longa duração:

    ./bigeye-mcp.sh start

  4. Adicione o wrapper à configuração do seu Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

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

  5. Reinicie o Claude Desktop.

Obtendo Suas Credenciais

  • BIGEYE_API_KEY — Gere no Bigeye em Configurações > Chaves de API
  • BIGEYE_BASE_URL — URL da sua instância Bigeye (ex.: https://app.bigeye.com)
  • BIGEYE_WORKSPACE_ID — Encontrado na sua URL do Bigeye após /w/ (ex.: https://app.bigeye.com/w/123/ → 123)

Variáveis de Ambiente Opcionais

  • BIGEYE_DEBUG — Defina como true para registro de depuração detalhado (padrão: false)
  • BIGEYE_TELEMETRY — Defina como false para desativar a telemetria anônima de uso (padrão: true). Veja Telemetria.

Telemetria

Para nos ajudar a melhorar o servidor, análises anônimas de uso (nome da ferramenta, duração, sucesso/erro) são enviadas ao Bigeye. Nenhum argumento, resultado ou dado é coletado. Defina BIGEYE_TELEMETRY=false para desativar.

Modos de Contêiner

Contêiner de Longa Duração (Recomendado)

Usa mcp-wrapper.sh + bigeye-mcp.sh com docker compose. O contêiner permanece em execução e o Claude Desktop se conecta via docker exec.

Nota: mcp-wrapper.sh depende do Docker Compose ler automaticamente o arquivo .env do diretório do projeto. Certifique-se de que seu arquivo .env esteja no mesmo diretório que docker-compose.yml.

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

Contêiner Efêmero

Um contêiner novo é iniciado para cada sessão do Claude Desktop e removido ao final.

{
  "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"
      ]
    }
  }
}

Gerenciamento de Contêiner

O script bigeye-mcp.sh gerencia o contêiner de longa duração:

./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

Configuração Multi-Ambiente

Para conectar a várias instâncias Bigeye (ex.: demonstração e produção), crie arquivos de ambiente separados e overrides de compose:

  1. Crie arquivos de ambiente para cada instância. Observe que os overrides de compose esperam nomes de variáveis prefixados (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

  2. Use os overrides de compose específicos do ambiente:

    # 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

  3. Adicione ambos à configuração do seu 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"
      ]
    }
  }
}

Ferramentas Disponíveis

Gerenciamento de Problemas

  • list_issues — Lista problemas de qualidade de dados no workspace (filtre por status, schema ou assignee_ids)
  • get_current_user — Obtém o usuário autenticado (id, e-mail, nome, workspaces); combine com list_issues(assignee_ids=[id]) para encontrar problemas atribuídos a você
  • get_issue — Obtém detalhes completos de um único problema pelo ID interno
  • search_issues — Encontra problemas pelo nome/número de exibição (ex.: "10921")
  • list_related_issues — Lista problemas relacionados a um problema via linhagem
  • list_table_issues — Lista problemas de qualidade de dados para uma tabela específica por nome
  • update_issue — Atualiza o status, prioridade ou adiciona uma mensagem de timeline a um problema
  • create_incident — Cria um incidente mesclando problemas relacionados
  • delete_incident_members — Remove problemas de um incidente
  • get_resolution_steps — Obtém etapas recomendadas de resolução para um problema

Métricas e Qualidade

  • list_table_metrics — Lista todas as métricas (monitores) configuradas em uma tabela
  • list_table_level_metrics — Lista tipos de métricas de nível de tabela (vs. nível de coluna)
  • create_metric — Cria uma nova métrica (monitor) em uma tabela com validação, mapeamento de enum e verificações de compatibilidade de tipo de coluna
  • get_table_profile — Obtém relatório de perfil de dados incluindo estatísticas e distribuição de colunas
  • create_profile_job — Enfileira um novo job de perfilamento de dados para uma tabela
  • get_profile_job_status — Verifica o status de um job de perfilamento

Varredura de Dados Sensíveis

  • list_data_classes — Lista categorias de classificação de dados (ex.: "Endereço de E-mail", "SSN dos EUA") com níveis de sensibilidade
  • get_scan_findings — Obtém resultados de varredura de classificação em nível de coluna mostrando onde dados sensíveis foram detectados

Catálogo de Dados

  • search_schemas — Pesquisa no catálogo de dados por schemas por nome (retorna ids + warehouse)
  • search_tables — Pesquisa no catálogo de dados por tabelas por nome (retorna ids, schema + warehouse)
  • search_columns — Pesquisa no catálogo de dados por colunas por nome (retorna ids, tipo + tabela pai)

Linhagem de Dados

  • get_lineage_graph — Obtém o grafo completo de linhagem (upstream/downstream/ambos) a partir de um nó inicial
  • get_lineage_node — Obtém detalhes de um nó de linhagem específico
  • list_lineage_node_issues — Lista problemas para um nó de linhagem pelo ID do nó
  • search_lineage_nodes — Encontra IDs de nós de linhagem por padrão de caminho (ex.: "WAREHOUSE/SCHEMA/TABLE")
  • lineage_explore_catalog — Explora tabelas no catálogo do Bigeye
  • lineage_delete_node — Exclui um nó de linhagem personalizado

Análise de Causa Raiz e Impacto

  • get_upstream_root_causes — Analisa linhagem upstream para identificar causas raiz de problemas
  • get_downstream_impact — Analisa impacto downstream de problemas em um nó de linhagem
  • get_issue_lineage_trace — Rastreia um problema de qualidade de dados de ponta a ponta pela linhagem
  • list_report_upstream_issues — Lista problemas upstream que afetam um relatório de BI ou dashboard

Rastreamento de Linhagem de Agentes

  • lineage_track_data_access — Rastreia ativos de dados acessados por um agente de IA
  • lineage_commit_agent — Confirma o acesso rastreado a dados no grafo de linhagem do Bigeye
  • lineage_get_tracking_status — Obtém o status atual do rastreamento de linhagem
  • lineage_clear_tracked_assets — Limpa todos os ativos de dados rastreados sem confirmar
  • lineage_cleanup_agent_edges — Limpa arestas de linhagem antigas para o agente de IA

Dimensões de Dados

  • list_dimensions — Lista todas as dimensões de qualidade de dados com seus mapeamentos de tipo de métrica
  • get_dimension — Obtém detalhes completos de uma única dimensão por ID
  • create_dimension — Cria uma nova Dimensão de Dados
  • update_dimension — Atualiza o nome ou descrição de uma dimensão
  • delete_dimension — Exclui uma Dimensão de Dados
  • get_table_dimension_coverage — Analisa lacunas de cobertura de dimensão para uma tabela (recomendado para "o que está faltando em monitoramento?")
  • get_column_dimension_coverage — Analisa cobertura de dimensão para colunas específicas em uma tabela

Tags

  • list_tags — Lista ou pesquisa tags do workspace
  • create_tag — Cria uma nova tag com cor opcional
  • update_tag — Atualiza o nome ou cor de uma tag
  • delete_tag — Exclui uma tag
  • tag_entity — Aplica uma tag a qualquer entidade (métrica, tabela, coluna, etc.)
  • untag_entity — Remove uma tag de uma entidade
  • list_entity_tags — Lista todas as tags em uma entidade específica

Glossário de Negócios

  • list_glossary_terms — Lista ou pesquisa termos do glossário de negócios
  • create_glossary_term — Cria um novo termo de glossário
  • update_glossary_term — Atualiza um termo de glossário (add_synonyms acrescenta sem sobrescrever sinônimos existentes)
  • delete_glossary_term — Exclui um termo de glossário e seus links de entidade
  • link_glossary_term_to_entity — Vincula um termo a uma fonte, schema, tabela ou coluna
  • unlink_glossary_term_from_entity — Remove o link de um termo a uma entidade
  • get_glossary_term_links — Lista as entidades vinculadas a um termo
  • get_entity_glossary_terms — Lista os termos vinculados a uma entidade

Sistema

  • get_health_status — Verifica a saúde e conectividade da API do Bigeye
  • list_resources — Lista todos os recursos MCP disponíveis
  • list_data_sources — Lista todas as fontes de dados/warehouses conectadas ao Bigeye

Recursos e Prompts

Recursos:

  • bigeye://auth/status — Status atual de autenticação
  • bigeye://health — Status de saúde da API
  • bigeye://config — Configuração atual do servidor
  • bigeye://issues — Todos os problemas do workspace configurado
  • bigeye://issues/active — Problemas ativos com filtragem
  • bigeye://issues/recent — Problemas resolvidos ou atualizados recentemente

Prompts:

  • authentication_flow — Guia para configurar autenticação
  • check_connection_info — Guia para verificar conexão com a API
  • merge_issues_example — Exemplos para mesclar problemas
  • lineage_analysis_examples — Exemplos para análise de linhagem

Rastreamento de Linhagem de Agentes

O servidor inclui rastreamento abrangente de linhagem para agentes de IA. Use a ferramenta lineage_track_data_access para registrar ativos de dados acessados durante uma sessão de agente e depois lineage_commit_agent para persistir no grafo de linhagem do Bigeye. Veja as descrições das ferramentas acima para detalhes completos.

Configuração de Desenvolvimento

Para desenvolvimento local sem Docker:

  1. Instale Python 3.12+
  2. Crie um ambiente virtual: 
    python -m venv venv
source venv/bin/activate
  3. Instale as dependências: 
    pip install -r requirements.txt
  4. Defina as variáveis de ambiente: 
    export BIGEYE_API_KEY="your_api_key"
export BIGEYE_BASE_URL="https://app.bigeye.com"
export BIGEYE_WORKSPACE_ID="your_workspace_id"
  5. Execute o servidor: 
    python server.py

Testes

# 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

Veja tests/README.md para detalhes sobre a suíte de testes.

Solução de Problemas

Variáveis de Ambiente Ausentes

  • Verifique se seu arquivo .env ou a configuração do Claude Desktop contém todas as variáveis necessárias
  • Os nomes das variáveis diferenciam maiúsculas de minúsculas
  • Reinicie o Claude Desktop após alterações na configuração

Erros de Autenticação

  • Verifique se sua chave de API é válida e possui as permissões apropriadas
  • O ID do workspace deve ser um número
  • A URL da instância não deve ter barra final

Problemas de Conexão

  • Verifique se a URL da instância Bigeye está acessível
  • Verifique configurações de firewall/proxy
  • Ative o modo de depuração: BIGEYE_DEBUG=true

Contêiner Não Inicia

  • Verifique se o Docker está em execução: docker info
  • Verifique se a imagem existe: docker images | grep bigeye
  • Verifique os logs: ./bigeye-mcp.sh logs

Diretório ~/.bigeye-mcp

O docker-compose.yml monta ~/.bigeye-mcp no contêiner para armazenamento persistente de credenciais. O Docker criará este diretório automaticamente se não existir. Você não precisa colocar nada nele manualmente — é usado internamente pelo servidor.