Bigeye MCP Server

Bigeye의 데이터 품질 모니터링 플랫폼과 Datawatch API를 통해 상호작용합니다. 동적 API 키 인증을 지원합니다.

GitHub

문서

Bigeye MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with the Bigeye Data Observability platform.

Prerequisites

  • Docker (Docker Desktop or Docker Engine)

Quick Start

  1. Build the Docker image:

    ./build-docker.sh

  2. Create a .env file with your credentials (see .env.example):

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

  3. Start the long-lived container:

    ./bigeye-mcp.sh start

  4. Add the wrapper to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

  5. Restart Claude Desktop.

Getting Your Credentials

  • BIGEYE_API_KEY — Generate in Bigeye under Settings > API Keys
  • BIGEYE_BASE_URL — Your Bigeye instance URL (e.g. https://app.bigeye.com)
  • BIGEYE_WORKSPACE_ID — Found in your Bigeye URL after /w/ (e.g. https://app.bigeye.com/w/123/ → 123)

Optional Environment Variables

  • BIGEYE_DEBUG — Set to true for verbose debug logging (default: false)
  • BIGEYE_TELEMETRY — Set to false to disable anonymous usage telemetry (default: true). See Telemetry.

Telemetry

To help us improve the server, anonymous usage analytics (tool name, duration, success/error) are sent to Bigeye. No arguments, results, or data are ever collected. Set BIGEYE_TELEMETRY=false to turn it off.

Container Modes

Long-Lived Container (Recommended)

Uses mcp-wrapper.sh + bigeye-mcp.sh with docker compose. The container stays running and Claude Desktop connects via docker exec.

Note: mcp-wrapper.sh relies on Docker Compose automatically reading the .env file from the project directory. Make sure your .env file is in the same directory as docker-compose.yml.

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

Ephemeral Container

A fresh container spins up for each Claude Desktop session and is removed when done.

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

Container Management

The bigeye-mcp.sh script manages the long-lived container:

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

Multi-Environment Setup

To connect to multiple Bigeye instances (e.g. demo and production), create separate environment files and compose overrides:

  1. Create environment files for each instance. Note that the compose overrides expect prefixed variable names (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 the environment-specific compose overrides:

    # 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. Add both to your Claude Desktop config:

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

Available Tools

Issue Management

  • list_issues — List data quality issues across the workspace (filter by status, schema, or assignee_ids)
  • get_current_user — Get the authenticated user (id, email, name, workspaces); pair with list_issues(assignee_ids=[id]) to find issues assigned to you
  • get_issue — Get full details for a single issue by its internal ID
  • search_issues — Find issues by their display name/number (e.g. "10921")
  • list_related_issues — List issues related to a given issue via lineage
  • list_table_issues — List data quality issues for a specific table by name
  • update_issue — Update an issue's status, priority, or add a timeline message
  • create_incident — Create an incident by merging related issues
  • delete_incident_members — Remove issues from an incident
  • get_resolution_steps — Get recommended resolution steps for an issue

Metrics & Quality

  • list_table_metrics — List all metrics (monitors) configured on a table
  • list_table_level_metrics — List metric types that are table-level (vs column-level)
  • create_metric — Create a new metric (monitor) on a table with validation, enum mapping, and column-type compatibility checks
  • get_table_profile — Get data profile report including column statistics and distribution
  • create_profile_job — Queue a new data profiling job for a table
  • get_profile_job_status — Check the status of a profiling job

Sensitive Data Scanning

  • list_data_classes — List data classification categories (e.g., "Email Address", "US SSN") with sensitivity levels
  • get_scan_findings — Get column-level classification scan results showing where sensitive data was detected

Data Catalog

  • search_schemas — Search the data catalog for schemas by name (returns ids + warehouse)
  • search_tables — Search the data catalog for tables by name (returns ids, schema + warehouse)
  • search_columns — Search the data catalog for columns by name (returns ids, type + parent table)

Data Lineage

  • get_lineage_graph — Get the full lineage graph (upstream/downstream/both) from a starting node
  • get_lineage_node — Get details for a specific lineage node
  • list_lineage_node_issues — List issues for a lineage node by its node ID
  • search_lineage_nodes — Find lineage node IDs by path pattern (e.g. "WAREHOUSE/SCHEMA/TABLE")
  • lineage_explore_catalog — Explore tables in Bigeye's catalog
  • lineage_delete_node — Delete a custom lineage node

Root Cause & Impact Analysis

  • get_upstream_root_causes — Analyze upstream lineage to identify root causes of issues
  • get_downstream_impact — Analyze downstream impact of issues at a lineage node
  • get_issue_lineage_trace — Trace a data quality issue end-to-end through lineage
  • list_report_upstream_issues — List upstream issues affecting a BI report or dashboard

Agent Lineage Tracking

  • lineage_track_data_access — Track data assets accessed by an AI agent
  • lineage_commit_agent — Commit tracked data access to Bigeye's lineage graph
  • lineage_get_tracking_status — Get the current status of lineage tracking
  • lineage_clear_tracked_assets — Clear all tracked data assets without committing
  • lineage_cleanup_agent_edges — Clean up old lineage edges for the AI agent

Data Dimensions

  • list_dimensions — List all data-quality dimensions with their metric type mappings
  • get_dimension — Get full details for a single dimension by ID
  • create_dimension — Create a new Data Dimension
  • update_dimension — Update a dimension's name or description
  • delete_dimension — Delete a Data Dimension
  • get_table_dimension_coverage — Analyze dimension coverage gaps for a table (recommended for "what monitoring is missing?")
  • get_column_dimension_coverage — Analyze dimension coverage for specific columns in a table

Tags

  • list_tags — List or search workspace tags
  • create_tag — Create a new tag with optional color
  • update_tag — Update a tag's name or color
  • delete_tag — Delete a tag
  • tag_entity — Apply a tag to any entity (metric, table, column, etc.)
  • untag_entity — Remove a tag from an entity
  • list_entity_tags — List all tags on a specific entity

System

  • get_health_status — Check the health and connectivity of the Bigeye API
  • list_resources — List all available MCP resources
  • list_data_sources — List all data sources/warehouses connected to Bigeye

Resources & Prompts

Resources:

  • bigeye://auth/status — Current authentication status
  • bigeye://health — API health status
  • bigeye://config — Current server configuration
  • bigeye://issues — All issues from the configured workspace
  • bigeye://issues/active — Active issues with filtering
  • bigeye://issues/recent — Recently resolved or updated issues

Prompts:

  • authentication_flow — Guide for setting up authentication
  • check_connection_info — Guide for verifying API connection
  • merge_issues_example — Examples for merging issues
  • lineage_analysis_examples — Examples for lineage analysis

Agent Lineage Tracking

The server includes comprehensive lineage tracking for AI agents. Use the lineage_track_data_access tool to record data assets accessed during an agent session, then lineage_commit_agent to persist them to Bigeye's lineage graph. See the tool descriptions above for full details.

Development Setup

For local development without Docker:

  1. Install Python 3.12+
  2. Create a virtual environment: 
    python -m venv venv
source venv/bin/activate
  3. Install dependencies: 
    pip install -r requirements.txt
  4. Set environment variables: 
    export BIGEYE_API_KEY="your_api_key"
export BIGEYE_BASE_URL="https://app.bigeye.com"
export BIGEYE_WORKSPACE_ID="your_workspace_id"
  5. Run the server: 
    python server.py

Testing

# 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

See tests/README.md for details on the test suite.

Troubleshooting

Missing Environment Variables

  • Check your .env file or Claude Desktop config contains all required variables
  • Variable names are case-sensitive
  • Restart Claude Desktop after config changes

Authentication Errors

  • Verify your API key is valid with appropriate permissions
  • Workspace ID must be a number
  • Instance URL should have no trailing slash

Connection Issues

  • Verify the Bigeye instance URL is accessible
  • Check for firewall/proxy settings
  • Enable debug mode: BIGEYE_DEBUG=true

Container Not Starting

  • Check Docker is running: docker info
  • Verify image exists: docker images | grep bigeye
  • Check logs: ./bigeye-mcp.sh logs

~/.bigeye-mcp Directory

The docker-compose.yml mounts ~/.bigeye-mcp into the container for persistent credential storage. Docker will create this directory automatically if it doesn't exist. You don't need to put anything in it manually — it's used internally by the server.