Wandb MCP Server

W&B MCP服务器

通过模型上下文协议使用自然语言查询和分析您的权重和偏差数据。

 

 

______________________________________________________________________

这个服务器能做什么？

Example Use Cases (click command to copy)

*“浏览我上次在grpo cuda/axoltl grpo训练的最后100条轨迹，告诉我为什么我的强化学习实验的推出轨迹有时很糟糕？”*

Available Tools (14 tools)

架构优先工作流： 呼叫 infer_trace_schema_tool 先发现领域，然后 query_weave_traces_tool 具有精确的列和 detail_level:

• "schema" --仅限结构字段（快速浏览）
• "summary" --截断输入/输出（默认）
• "full" --所有未截断的内容（钻取特定的痕迹）

图表面板： create_wandb_report_tool 接受a panels LinePlots、BarPlots的参数，并与markdown一起运行比较。

文档搜索： search_wandb_docs_tool 代理 旺布艾博士 因此，您可以从单个MCP连接中获得数据工具+文档搜索。禁用 WANDB_MCP_PROXY_DOCS=false 如果您单独连接MCP文档。

Usage Tips (best practices)

→ 提供您的W&B项目和实体名称\ LLM不是读心术者，请确保向LLM指定W&B实体和W&B项目。

→ 避免问过于宽泛的问题\ 诸如“我的最佳评价是什么？”之类的问题可能过于宽泛，通过将问题细化为更具体的问题，例如“哪个eval的f1得分最高？”，你会更快地得到答案

→ 确保检索到所有数据\ 当问诸如“我的最佳运行/评估是什么？”之类的广泛而一般的问题时，最好让LLM检查它是否检索到了所有可用的运行。MCP工具旨在获取正确数量的数据，但有时LLM可能会倾向于只检索最新运行或最后N次运行。

______________________________________________________________________

快速开始

我们建议使用我们的 托管服务器 在 https://mcp.withwandb.com -无需安装！

🔑 从获取API密钥 wandb.ai/授权

🌐 要连接到 W&B专用/On Prem实例 目前只有 本地 MCP配置可以与其他配置一起使用 WANDB_BASE_URL env变量（默认值为 api.wandb.ai)

光标

One-click installation

• 点击上面的按钮，自动将配置添加到Cursor
• 然后在相应字段中添加您的WANDB_API_KEY Bearer YOUR_API_KEY 并连接

有关手动或本地安装，请参阅 选项2 在......下面

OpenAI响应API

Python client setup

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)

备注：OpenAI的MCP是服务器端的，因此localhost URL不起作用。对于本地服务器，请参阅 选项2 与ngrok。

克劳德代码

One-command installation

# run in terminal
claude mcp add --transport http wandb https://mcp.withwandb.com/mcp --scope user --header "Authorization: Bearer "

有关本地安装，请参阅 选项2 在......下面

OpenAI Codex

One-command installation

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

有关本地安装，请参阅 选项2 在......下面

Gemini CLI

One-command installation

# 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

扩展将使用以下配置 gemini-extension.json 指向托管服务器。

有关本地安装，请参阅 选项2 在......下面

VSCode

Settings configuration

# 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"
      }
    }
  }
}

有关本地安装，请参阅 选项2 在......下面

米斯特拉尔聊天

Configuration setup Mistral is currently the best supported Chat assistant based on API-key based authentication. Simply navigate to "Connectors" and 1) paste in the URL https://mcp.withwandb.com/mcp and 2) select API Key Authentication and paste WANDB API key.

克劳德桌面版

Configuration setup

添加到您的Claude配置文件中。Claude桌面目前不支持添加远程MCP，因此我们正在添加本地MCP。请注意将完整路径添加到 uv 对于该命令，因为Claude Desktop可能找不到您的 uv 否则安装。

# 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": ""
      }
    }
  }
}

重新启动Claude Desktop以激活。

我们正在努力添加OAuth支持，以便与ChatGPT集成。

______________________________________________________________________

通用安装指南

Option 1: Hosted Server (Recommended)

托管服务器提供零配置体验，具有企业级可靠性。此服务器由W&B团队维护，自动更新新功能，并可扩展以处理任何工作负载。非常适合您希望专注于机器学习工作而不是基础设施的团队和生产用例。

使用公共服务器

最简单的方法是使用我们的托管服务器 https://mcp.withwandb.com.

优点：

• ✅ 零安装
• ✅ 始终保持最新状态
• ✅ 自动缩放
• ✅ 无需维护

只需使用中显示的配置 快速开始.

Option 2: Local Development (STDIO)

在本地运行MCP服务器进行开发、测试或需要完全控制数据时。本地服务器直接在您的计算机上运行，桌面客户端使用STDIO传输，基于web的客户端使用HTTP传输。非常适合想要定制服务器或在气隙环境中工作的开发人员。 请参阅下面的客户端特定安装.

在本地运行服务器

快速入门：

# 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

📖 有关完整的命令行选项和环境变量，请参阅 命令行参考 在“更多信息”部分。

手动配置

添加到您的MCP客户端配置中（有关特定于客户端的详细配置，请参阅下文）：

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

光标

1. 打开光标设置(⌘, 或 Ctrl,)
2. 导航至 特性 → 模型上下文协议
3. 点击 “从注册表安装” 或 “添加MCP服务器”
4. 搜索“wandb”或输入：

- 名字: wandb - 统一资源定位符: https://mcp.withwandb.com/mcp - API密钥：您的W&B API密钥

手动托管配置 mcp.json:

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

手动本地（专用或本地）配置 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 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

克劳德代码

添加 --scope user 用于全局配置。

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

克劳德桌面版

和上面一样。

# 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": "",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com", # optional
      }
    }
  }
}

重新启动Claude Desktop以激活。

使用ngrok进行测试（适用于服务器端客户端）

对于像OpenAI和LeChat这样需要公共网址的客户：

# 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

Option 3: Self-Hosted HTTP Server (Advanced)

这个公共存储库侧重于STDIO传输。如果你需要一个完全托管的HTTP部署（Docker、Cloud Run、Hugging Face等），从这个代码库开始，在一个单独的仓库中添加你自己的HTTP入口点。W&B维护的生产级托管服务器现在位于一个构建在其之上的私有存储库中。

在本地运行HTTP服务器

对于轻量级实验和测试，您可以直接运行FastMCP HTTP传输：

# 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

📖 有关所有可用的命令行选项，请参阅 命令行参考 在“更多信息”部分。

备注：客户必须继续根据MCP规范通过承载令牌提供自己的W&B API密钥。

Option 4: Dedicated / On-Prem Deployment

对于W&B专用和On Prem客户，MCP服务器可作为 operator-wandb Helm图表。用你的一行启用它 WeightsAndBiases CR：

mcp-server:
  install: true

服务器可在以下位置访问 https:///mcp。它会自动连接到您的集群内Weave跟踪服务器和W&B API。

要求：

• weave-trace 必须安装(weave-trace.install: true)
• 操作图版本>=0.42.0
• 图像 wandb/mcp-server:0.3.0 或之后

客户端配置 对于专用实例：

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

联系您的W&B客户团队，在您的专用部署中启用MCP。

______________________________________________________________________

更多信息

命令行参考

在本地运行服务器时，您可以使用命令行参数自定义其行为：

可用参数

备注：参数使用下划线（例如。， --wandb_api_key)，而不是破折号。

环境变量

使用示例

STDIO传输（桌面客户端的默认设置）：

# Basic usage with environment variable
export WANDB_API_KEY="your-api-key"
uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

# Or with API key as argument
uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server --wandb_api_key your-api-key

HTTP传输（用于测试和开发）：

# Basic HTTP server on localhost:8080
uvx wandb_mcp_server --transport http --host 127.0.0.1 --port 8080

# Bind to all interfaces with custom port
uvx wandb_mcp_server --transport http --host 0.0.0.0 --port 9090

使用Weave跟踪（记录MCP对W&B的调用）：

uvx wandb_mcp_server \
  --transport http \
  --port 8080 \
  --weave_entity my-team \
  --weave_project mcp-monitoring

查看所有选项：

uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server --help

贡献与发布

• 贡献.md --开发设置、测试、PR流程、架构概述
• 发布.md --版本升级、发布清单、部署管道

关键资源

• W&B文档: 旺布艾博士
• 编织文档: 编织门
• MCP规范: 模型上下文协议.io

示例代码

Complete OpenAI Example

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)

发展

运行测试

单元测试在没有API密钥或网络访问的情况下运行：

pip install -e ".[test]"
pytest tests/ -v

CI通过GitHub Actions在每次推送和PR时自动运行。

双回购模式

内部仓库将公共仓库安装为pip依赖项。

支持

• 电子邮件support@wandb.com