Bigeye MCP Server (Beta)

The Bigeye MCP Server connects an AI assistant like Claude to your Bigeye data observability platform. Once it's running, you can ask Claude about your data quality issues or lineage and it pulls the answers straight from Bigeye, right inside your chat.

This guide walks you through getting it running with Claude Desktop or Claude Code. The whole thing takes about ten minutes.

What you'll need

Before you start, make sure you have:

• Docker Desktop. Download it here if you don't already have it.
• Claude Desktop or Claude Code, whichever you want to connect the server to.
• Three pieces of info from Bigeye:
  • API key: in Bigeye, go to Settings → API Keys and generate one.
  • Base URL: your Bigeye instance address, usually https://app.bigeye.com.
  • Workspace ID: the number in your Bigeye URL right after /w/. For example, in https://app.bigeye.com/w/123/ the workspace ID is 123.

Keep these three handy. You'll add them to a file in Step 3.

Setup steps

These first three steps are the same no matter which client you use. Once they're done, jump to the section for your client.

1. Get the code

Clone or download this repository to your computer, then open a terminal in the project folder.

2. Build the Docker image

./build-docker.sh

This packages the server so Docker can run it. You only need to do this once, and again whenever you update the code.

3. Add your credentials

Copy the example file and fill in your values:

cp .env.example .env

Open the new .env file in a text editor and replace the placeholders with the three values you gathered earlier:

BIGEYE_API_KEY=your_api_key_here
BIGEYE_BASE_URL=https://app.bigeye.com
BIGEYE_WORKSPACE_ID=your_workspace_id_here
BIGEYE_DEBUG=false

Keep this .env file in the same folder as docker-compose.yml. That's where the server reads your credentials from.

The server is now built and configured. Connect your client below. You don't need to start anything by hand; the first time your client connects, it starts the container for you.

Connecting to Claude Desktop

Open Claude Desktop's config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a bigeye entry that points to the wrapper script:

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

Replace /absolute/path/to/mcp-wrapper.sh with the full path to the mcp-wrapper.sh file in the project folder. The wrapper reads your credentials from .env, so you don't put any secrets in this config.

Then quit Claude Desktop and open it again so it picks up the change.

Connecting to Claude Code

Claude Code (the command-line tool) doesn't use a claude_desktop_config.json. You register the server with a command or a small project file instead.

Run this from your terminal, using the full path to the wrapper script:

claude mcp add bigeye -- /absolute/path/to/mcp-wrapper.sh

By default this adds Bigeye for you in the current project. Add -s user to make it available in every project, or -s project to save it to a shared .mcp.json file.

Confirm it's connected

Run claude mcp list to see bigeye in the list, or type /mcp inside a Claude Code session.

Check that it worked

Ask Claude something like "Check my Bigeye connection status." If everything is wired up, it'll use the Bigeye tools to answer.

You can also check the server from your terminal:

./bigeye-mcp.sh status   # is it running?
./bigeye-mcp.sh logs     # see what it's doing

Everyday commands

Use the ./bigeye-mcp.sh script to manage the server:

Other options

This guide covers the recommended setup, but there are a few alternatives.

Run without a long-lived container (ephemeral mode). Instead of the wrapper script, you can have your client start a fresh container for each session and pass credentials directly. In Claude Desktop, use these arguments in place of the wrapper path:

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

In Claude Code, the same thing is one command:

claude mcp add bigeye -- docker run -i --rm \
  -e BIGEYE_API_KEY=your_api_key_here \
  -e BIGEYE_BASE_URL=https://app.bigeye.com \
  -e BIGEYE_WORKSPACE_ID=your_workspace_id_here \
  bigeye-mcp-server:latest

The trade-off is that your credentials live in the config file instead of .env.

Connect to more than one Bigeye instance. A multi-environment setup lets you point at a demo and a production workspace at the same time. See the project's README.md for the details.

Any other MCP-compatible client connects the same way. Point it at the wrapper script or the Docker command above.

Troubleshooting

Claude doesn't show any Bigeye tools.
In Claude Desktop, restart the app after editing the config, and check that the path to mcp-wrapper.sh is a full, absolute path, not a shortcut like ~/ or a relative path. In Claude Code, run claude mcp list to confirm the server is registered.

The server won't connect.
Run ./bigeye-mcp.sh status to see if it's running. If it isn't, start it with ./bigeye-mcp.sh start.

You're getting credential or authentication errors.
Re-check the values in your .env file. The workspace ID must be a number, and the API key and base URL need to match your Bigeye instance.

Still stuck?
Run ./bigeye-mcp.sh logs to see what the server is reporting. The error messages there usually point to the problem.