W&B MCP Server

"Go through the last 100 traces of my last training run in grpo-cuda/axolotl-grpo and tell me why rollout traces of my RL experiment were bad sometimes?"

Read-only deployment mode: Set WANDB_MCP_READ_ONLY=true to omit the two write tools, create_wandb_report_tool and log_analysis_to_wandb, while keeping every existing read tool. query_wandb_tool is query-only in every mode, regardless of this setting.

Weave Agents (OTel) tools — these read the OpenTelemetry/GenAI agent-spans data plane (the Agents tab), which is separate from the classic Weave calls above:

These tools are disabled by default. Enable them with WANDB_MCP_ENABLE_WEAVE_AGENT_TOOLS=true.

Schema-first workflow: Call infer_trace_schema_tool first to discover fields, then query_weave_traces_tool with precise columns and detail_level:

• "schema" -- structural fields only (fast browsing)
• "summary" -- truncated inputs/outputs (default)
• "full" -- everything untruncated (drill into specific traces)

Chart panels: create_wandb_report_tool accepts a panels parameter for LinePlots, BarPlots, run comparisons, custom Vega charts, and ordered report layouts. Use panel_grid when multiple charts should share one runset, and use heading plus markdown blocks to interleave narrative sections with charts.

Docs search: search_wandb_docs_tool proxies docs.wandb.ai so you get data tools + documentation search from a single MCP connection. Disable with WANDB_MCP_PROXY_DOCS=false if you connect the docs MCP separately.

→ Provide your W&B project and entity name LLMs are not mind readers, ensure you specify the W&B Entity and W&B Project to the LLM.

→ Avoid asking overly broad questions Questions such as "what is my best evaluation?" are probably overly broad and you'll get to an answer faster by refining your question to be more specific such as: "what eval had the highest f1 score?"

→ Ensure all data was retrieved When asking broad, general questions such as "what are my best performing runs/evaluations?" it's always a good idea to ask the LLM to check that it retrieved all the available runs. The MCP tools are designed to fetch the correct amount of data, but sometimes there can be a tendency from the LLMs to only retrieve the latest runs or the last N runs.

• Click on the button above to automatically add the config to Cursor
• Then add your WANDB_API_KEY in the respective field Bearer YOUR_API_KEY and connect

For manual or local installation, see Option 2 below.

from openai import OpenAI
import os

client = OpenAI()

resp = client.responses.create(
 model="gpt-4o",
 tools=[{
     "type": "mcp",
     "server_url": "https://mcp.withwandb.com/mcp",
     "authorization": os.getenv('WANDB_API_KEY'),
     "server_label": "WandB_MCP",
 }],
 input="How many traces are in my project?"
)
print(resp.output_text)

Note: OpenAI's MCP is server-side, so localhost URLs won't work. For local servers, see Option 2 with ngrok.

# run in terminal
claude mcp add --transport http wandb https://mcp.withwandb.com/mcp --scope user --header "Authorization: Bearer <your-api-key-here>"

For local installation, see Option 2 below.

# run in terminal
export WANDB_API_KEY=<your-api-key>
codex mcp add wandb --url https://mcp.withwandb.com/mcp --bearer-token-env-var WANDB_API_KEY

For local installation, see Option 2 below.

# Set your API key
export WANDB_API_KEY="your-api-key-here"

# Install the extension
gemini extensions install https://github.com/wandb/wandb-mcp-server

The extension will use the configuration from gemini-extension.json pointing to the hosted server.

For local installation, see Option 2 below.

# Open settings
code ~/.vscode/mcp.json # or global mcp.json file

{
  "servers": {
    "wandb": {
      "type": "http",
      "url": "https://mcp.withwandb.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_WANDB_API_KEY"
      }
    }
  }
}

For local installation, see Option 2 below.

Mistral Le Chat is currently the best supported chat assistant for API-key based MCP authentication.

Use the Custom MCP Connector flow:

1. Open Le Chat and go to Connectors.
2. Add a custom MCP connector.
3. Set the server URL to https://mcp.withwandb.com/mcp.
4. Select HTTP Bearer Token or API Key authentication.
5. Paste your W&B API key from wandb.ai/authorize.

If the UI asks for a token value, paste the raw W&B API key. If it asks for the full Authorization header value, use Bearer <your-wandb-api-key>.

If adding the W&B connector from the Le Chat connector directory returns an integrations.addIntegrationFromStore 500 error, use the Custom MCP Connector flow above. That error happens in Mistral's connector-store add flow before Le Chat reaches the W&B MCP endpoint.

Add to your Claude config file. Claude desktop currently doesn't support remote MCPs to be added so we're adding the local MCP. Be careful to add the full path to uv for the command because Claude Desktop potentially doesn't find your uv installation otherwise.

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wandb": {
     "command": "/Users/niware_wb/.local/bin/uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/wandb-mcp-server",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "<your-api-key>"
      }
    }
  }
}

Restart Claude Desktop to activate.

The hosted server provides a zero-configuration experience with enterprise-grade reliability. This server is maintained by the W&B team, automatically updated with new features, and scales to handle any workload. Perfect for teams and production use cases where you want to focus on your ML work rather than infrastructure.

Using the Public Server

The easiest way is using our hosted server at https://mcp.withwandb.com.

Benefits:

• ✅ Zero installation
• ✅ Always up-to-date
• ✅ Automatic scaling
• ✅ No maintenance

Simply use the configurations shown in Quick Start.

Run the MCP server locally for development, testing, or when you need full control over your data. The local server runs directly on your machine with STDIO transport for desktop clients or HTTP transport for web-based clients. Ideal for developers who want to customize the server or work in air-gapped environments. See below for client specific installation.

Running the Server Locally

Quick Start:

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the server
uv pip install git+https://github.com/wandb/wandb-mcp-server

# Run with STDIO transport (for desktop clients)
export WANDB_API_KEY="your-api-key"
uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

📖 For complete command line options and environment variables, see the Command Line Reference in the More Information section.

Manual Configuration

Add to your MCP client config (for detailed client-specific configs see below):

{
  "mcpServers": {
    "wandb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/wandb-mcp-server",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "YOUR_API_KEY",
        "WANDB_BASE_URL": "YOUR_BASE_URL", #optional for dedicated or on-prem installations
      }
    }
  }
}

Cursor

1. Open Cursor Settings (⌘, or Ctrl,)
2. Navigate to Features → Model Context Protocol
3. Click "Install from Registry" or "Add MCP Server"
4. Search for "wandb" or enter:
   • Name: wandb
   • URL: https://mcp.withwandb.com/mcp
   • API Key: Your W&B API key

Manual hosted config in mcp.json:

"wandb": {
  "transport": "http",
  "url": "https://mcp.withwandb.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR-API_KEY",
    "Accept": "application/json, text/event-stream"
  }
}

Manual local (dedicated or on-prem) config in mcp.json:

"wandb": {
  "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/wandb/wandb-mcp-server",
      "wandb_mcp_server"
    ],
    "env": {
      "WANDB_API_KEY": "YOUR-API_KEY",
      "WANDB_BASE_URL": "https://your-wandb-instance.example.com", # optional
    }
}

Codex

codex mcp add wandb \
    --env WANDB_API_KEY=your_api_key_here \
    --env WANDB_BASE_URL=https://your-wandb-instance.example.com \
    -- uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

Claude Code

Add --scope user for global config.

claude mcp add wandb -e WANDB_API_KEY=your-api-key -e WANDB_BASE_URL=your-base-url -- uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

Claude Desktop

Same as above.

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wandb": {
     "command": "/Users/niware_wb/.local/bin/uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/wandb-mcp-server",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "<your-api-key>",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com", # optional
      }
    }
  }
}

Restart Claude Desktop to activate.

Testing with ngrok (for server-side clients)

For clients like OpenAI and LeChat that require public URLs:

# 1. Start HTTP server
uvx wandb-mcp-server --transport http --port 8080

# 2. Expose with ngrok
ngrok http 8080

# 3. Use the ngrok URL in your client configuration

This public repository focuses on the STDIO transport. If you need a fully managed HTTP deployment (Docker, Cloud Run, Hugging Face, etc.), start from this codebase and add your own HTTP entrypoint in a separate repo. The production-grade hosted server maintained by W&B now lives in a private repository built on top of this one.

Running HTTP Server Locally

For lightweight experimentation and testing, you can run the FastMCP HTTP transport directly:

# Basic HTTP server
uvx wandb_mcp_server --transport http --host 0.0.0.0 --port 8080

# With Weave tracing enabled
uvx wandb_mcp_server \
  --transport http \
  --host 0.0.0.0 \
  --port 8080 \
  --weave_entity your-entity \
  --weave_project mcp-server-logs

📖 For all available command line options, see the Command Line Reference in the More Information section.

Note: Clients must continue to provide their own W&B API key via Bearer token per the MCP spec.

For W&B Dedicated and On-Prem customers, the MCP server is available as an optional subchart in the operator-wandb Helm chart. Enable it with one line in your WeightsAndBiases CR:

mcp-server:
  install: true

The server becomes accessible at https://<your-instance>/mcp. It automatically connects to your in-cluster Weave trace server and W&B API.

Requirements:

• weave-trace must be installed (weave-trace.install: true)
• Operator chart version >= 0.42.0
• Image wandb/mcp-server:0.3.0 or later

Client configuration for dedicated instances:

{
  "mcpServers": {
    "wandb": {
      "url": "https://your-instance.wandb.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_WANDB_API_KEY"
      }
    }
  }
}

Contact your W&B account team to enable MCP on your dedicated deployment.

from openai import OpenAI
from dotenv import load_dotenv
import os

load_dotenv()

client = OpenAI()

resp = client.responses.create(
    model="gpt-4o",  # Use gpt-4o for larger context window
    tools=[
        {
            "type": "mcp",
            "server_label": "wandb",
            "server_description": "Query W&B data",
            "server_url": "https://mcp.withwandb.com/mcp",
            "authorization": os.getenv('WANDB_API_KEY'),
            "require_approval": "never",
        },
    ],
    input="How many traces are in wandb-smle/hiring-agent-demo-public?",
)

print(resp.output_text)