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.

Ephemeral Container

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

Container Management

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

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