Bigeye MCP Server

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

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)

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.

{
  "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:

   cp .env.example .env.demo
   cp .env.example .env.app
   # Edit each with the appropriate credentials
   

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
• 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

Catalog Search

• search_schemas — Search for schemas by name (partial matching)
• search_tables — Search for tables by exact or partial name match
• search_columns — Search for columns by name (partial matching)

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://issues/all — All issues from the configured workspace

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 — see AGENT_LINEAGE_TRACKING.md for 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
   

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