Weights & Biases MCP Server

“查看我项目中最近的 100 条跟踪记录，并说明最常见的故障。”

只读部署模式： 将 WANDB_MCP_ACCESS_MODE=read-only 设为只读，以省略所有归类为写入的工具，包括 create_wandb_report_tool、log_analysis_to_wandb，以及（在 ARIA 配置中）aria_send_message。 query_wandb_tool 在所有模式下均为只读。可选择结构化 SDK 参数（entity_name、project_name、resource 和可选选择器），或旧版 query/variables 输入。结构化读取使用有文档说明的 W&B API，并在需要时采用由应用固定的投影，以避免对每个结果分别发起请求。GraphQL 模式保留了现有工具名称，可用于内省、未建模字段、别名，或结构化接口无法表达的读取形式。 GraphQL 兼容性： 旧版模式适用于所有受支持的工作负载和两种访问模式；无需新配置或额外权限。默认值为 max_items=100 和 items_per_page=20，并受活动工作负载的项目数／页数限制、截止时间和响应预算进一步约束。必须提供且仅提供一个查询操作，且不要将 query／variables 与结构化 SDK 选择器混用。变更、订阅、多个操作和混合模式输入都会在后端执行前被拒绝。独立的 query_wandb_graphql_tool 仍仅在 models-weave-graphql-compat 配置中可本地使用；通过 query_wandb_tool 使用 GraphQL 不需要这个额外工具。请参阅查询功能矩阵。

在受支持的 W&B 服务传输上，原始和固定的 GraphQL 响应会在 MCP JSON 解码前按 16 MiB 检查，并在解码后再次检查，结构上限为 500,000 个节点。超大结果会返回 response_too_large。这些是 SDK 收到 protobuf 信封后实施的 MCP 处理防护；它们不会限制网络传输字节数或后端工作量。

推荐的部署预设：

与 v0.3.7 的兼容性： 现有仅查询的 query_wandb_tool 调用可以继续使用 query 和可选的 variables 参数。结构化 SDK 参数是额外模式，并非强制迁移要求。每次调用只使用一种模式，并在升级时刷新客户端的工具定义。两种模式都适用授权和有界读取防护；工具名称和配置数量保持不变。

运行历史语义： 对显式的多键默认历史采样和范围集合读取，get_run_history_tool 会按 _step 对请求的指标序列进行外连接；如果没有 _step，则使用所选的 x 轴，这样在不同 wandb.log() 调用中记录的键就不会消失。多键范围读取会为每个指标使用一个独立的有界序列，每个请求最多包含八个序列。独立规格路径旨在同时涵盖活动／新同步历史以及导出的历史。多请求读取会对每个批次使用同一个刚观测到的上限 step 边界。固定快照查询会读取运行标识和一行完整、面向恢复的 historyTail；在有界历史读取之前，它不会加载完整配置、摘要、系统指标或历史键索引。samples 是所有请求键共享的最终行总预算，而非每个键的单独额度。只要预算允许，就会保留有界结果中的所有已观测稀疏点。如果有界／采样结果中没有出现可用的有限／非空值，诊断信息会报告 unobserved_keys；只有在已精确检查缺失情况时才会报告 missing_keys。自定义 x 轴必须与其指标出现在同一行，因为服务端不会自行插值。non_finite_counts 会报告有界源中观测到的 NaN 或 Infinity；这些无效的 JSON 数值会从返回行中省略，且只有在 key_counts_exact=true 时计数才是完整的。精确的 target_x 仍是点查找，而不是外连接读取。此路径使用固定的、由应用管理的仅查询投影，不接受调用方提供的 GraphQL，并且包含在每个受支持的托管工具配置中。

Weave Agents（OTel）工具——这些工具读取 OpenTelemetry／GenAI Agent 跨度数据平面（Agents 选项卡），该数据平面与上述经典 Weave 调用相互独立： 这些工具包含在显式的 models-weave-agents 和 models-weave-agents-aria 配置中，也保留在托管的 models-weave-agents-agent-lens 配置中。专用版 v0.4 会拒绝这三种配置。

以架构为先的工作流： 先调用 infer_trace_schema_tool 发现字段，再使用精确的列和 detail_level 调用 query_weave_traces_tool：

• "schema" -- 仅结构字段（快速浏览）
• "summary" -- 截断的输入/输出（默认）
• "full" -- 完整内容，不作截断（深入查看特定跟踪）

图表面板： create_wandb_report_tool 接受 panels 参数，可用于 LinePlots、BarPlots、运行比较、自定义 Vega 图表以及有序报告布局。当多个图表应共享同一个运行集时，请使用 panel_grid；使用 heading 和 markdown 块可在报告中交错呈现说明内容与图表。

文档搜索： search_wandb_docs_tool 代理 docs.wandb.ai，让你通过单个 MCP 连接使用数据工具和文档搜索。如果单独连接了文档 MCP，请设置 WANDB_MCP_PROXY_DOCS=false 禁用此功能。

若要搜索文档的可自托管副本（例如，与 W&B Server 版本匹配的文档），请将 DOCS_MCP_URL 设为其 MCP 端点，例如 http://localhost:3000/mcp。该端点必须像 docs.wandb.ai/mcp 一样，通过 Streamable HTTP 接受针对 search_weights_biases_documentation 的 JSON-RPC tools/call 请求。不会向其发送 W&B 凭据。使用 operator-wandb Helm chart 时，请设置 mcp-server.env.DOCS_MCP_URL。

文档查询最多接受 64 KiB 的 UTF-8 文本。代理会发起一个请求， 最多下载 4 MiB（或更低的已配置累积上限），并将返回的片段限制在响应令牌预算内。超大片段会附带截断提示；上游错误绝不会回显查询内容。

该软件包包含令牌计数词汇表，因此无需外部下载或可写的分词器缓存即可使用响应预算。

在托管版 v0.4 中，ARIA 工具需显式启用且仅限本地使用： 选择 models-weave-agents-aria，并将 WB_AGENT_BASE_URL 配置为获准的绝对 HTTPS 源站。仅有端点并不会启用这些工具。 WANDB_MCP_ACCESS_MODE=read-only 会省略 aria_send_message，同时保留 两个轮询工具。托管共享版和专用版配置均不支持 ARIA。

ARIA 轮询： ARIA 调用是异步的。aria_send_message 会返回一个轮次句柄，而 aria_get_turn 会在最多 30 秒内轮询一个轮次。若有多个待处理轮次，请使用 aria_get_turns，以便在一个共享轮询窗口内并发获取结果。轮询结果默认较为精简；只有在需要有界的原始服务快照时，才传入 include_turn=true。 Agent Lens 仅在受管部署中显式启用且仅限托管环境（自 v0.4.2 起）： W&B 托管 部署可以在 shared 工作负载中选择 models-weave-agents-agent-lens，并使用经运营方审核的 AGENT_LENS_BASE_URL。默认的 models-weave 配置文件和两个 Dedicated 配置文件均不包含这些工具，仅设置端点 并不会启用它们。请参阅 Agent Lens 工具指南。 该指南还介绍了端到端请求截止时间，以及针对调用方派生标识符的日志记录范围保护。

注册表组织解析： 如果省略 organization，注册表工具会使用经过身份验证的 请求中的 W&B 客户端。系统会自动选择唯一可访问的组织；如果调用方有权访问多个 组织，则会返回 organization_required，并附带有数量上限的候选列表。 集合列表会有意返回 aliases: null 和 aliases_loaded: false，而不是加载每个集合的版本别名。 需要别名时，请使用 list_artifact_versions_tool。

→ 提供 W&B 项目和实体名称 LLM 不会读心，请确保向 LLM 指定 W&B 实体和 W&B 项目。

→ 避免提出过于宽泛的问题 “我的最佳评估是什么？”之类的问题可能过于宽泛。将问题细化得更具体些，例如“哪个 eval 的 f1 分数最高？”，这样你会更快得到答案。

→ 检查宽泛问题的结果覆盖范围 集合和评估工具会报告 total_count、 returned_count、has_more、project_exhaustive、sampled 和 truncated 等字段。 对于宽泛的问题，请让客户端解释这些字段，而不要假设有界结果代表了整个项目。

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

手动或本地安装请参阅下方的 选项 2。

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 无法使用。请使用 W&B 托管端点或经过身份验证的 Helm 部署。

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

本地安装请参阅下方的 选项 2。

# 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

本地安装请参阅下方的 选项 2。

# 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。

# 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。

使用 Custom MCP Connector 流程：

1. 打开 Le Chat 并转到 Connectors。
2. 添加自定义 MCP 连接器。
3. 将服务 URL 设置为 https://mcp.withwandb.com/mcp。
4. 选择 HTTP Bearer Token 或 API Key 身份验证。
5. 粘贴从 wandb.ai/authorize 获取的 W&B API 密钥。

如果界面要求输入令牌值，请粘贴原始 W&B API 密钥。如果要求输入完整的 Authorization 标头值，请使用 Bearer <your-wandb-api-key>。

如需建立本地 STDIO 连接，请将服务添加到 Claude Desktop 配置中。如果桌面应用无法解析 shell PATH，请使用 uvx 的绝对路径。

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

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

{
  "mcpServers": {
    "wandb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/[email protected]",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "<your-api-key>"
      }
    }
  }
}

重启 Claude Desktop 以启用。

托管服务提供受管理的零安装体验。它采用受限的工作负载配置、请求截止时间和可重试的过载响应，在为多位用户提供服务的同时保护 W&B。

使用公共服务

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

优势：

• ✅ 无需安装
• ✅ 受管理且经过审核的版本更新
• ✅ 受管理的工作负载限制
• ✅ 无需维护服务

只需使用快速入门中所示的配置。

在本地运行 MCP 服务，以进行开发、测试，或在需要直接控制其配置时使用。本地服务在你的计算机上运行，通过 STDIO 传输与桌面客户端通信，或通过 HTTP 传输与基于 Web 的客户端通信。 它仍需要访问已配置的 W&B 实例，以及任何已启用的文档或遥测端点。请参阅下文中的客户端专属安装说明。

在本地运行服务

快速入门：

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

# Replace vX.Y.Z with a signed, available release from the release index.
export WANDB_API_KEY="your-api-key"
uvx --from git+https://github.com/wandb/[email protected] wandb_mcp_server

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

手动配置

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

{
  "mcpServers": {
    "wandb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/[email protected]",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "YOUR_API_KEY",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
      }
    }
  }
}

Cursor

1. 打开 Cursor 设置（⌘, 或 Ctrl,）
2. 转到 Features → Model Context Protocol
3. 点击 "Install from Registry" 或 "Add MCP Server"
4. 搜索 "wandb" 或输入：
   • 名称：wandb
   • URL：https://mcp.withwandb.com/mcp
   • API Key：你的 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/[email protected]",
      "wandb_mcp_server"
    ],
    "env": {
      "WANDB_API_KEY": "YOUR-API_KEY",
      "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
    }
}

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/[email protected] wandb_mcp_server

Claude Code

添加 --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/[email protected] wandb_mcp_server

Claude Desktop

与上文相同。

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

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

{
  "mcpServers": {
    "wandb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/[email protected]",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "<your-api-key>",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
      }
    }
  }
}

重启 Claude Desktop 以启用。

独立 HTTP 入口仅允许使用回环地址，不能通过 ngrok 或其他隧道对外发布。若要提供可远程访问的端点，请使用经过身份验证的托管包装器或 operator-wandb Helm 部署。

该软件包仅为本地开发提供未经身份验证的 Streamable HTTP 传输。使用前必须明确确认，并且仅接受回环地址绑定。生产环境中的 HTTP 服务请使用经过身份验证的托管包装器或 Helm 镜像。

在本地运行 HTTP 服务

如需进行轻量级实验和测试，可以直接运行 FastMCP HTTP 传输：

# Basic loopback HTTP server
export MCP_AUTH_DISABLED=true
uvx --from git+https://github.com/wandb/[email protected] wandb_mcp_server \
  --transport http \
  --host 127.0.0.1 \
  --port 8080

# With Weave tracing enabled
uvx --from git+https://github.com/wandb/[email protected] wandb_mcp_server \
  --transport http \
  --host 127.0.0.1 \
  --port 8080 \
  --weave_entity your-entity \
  --weave_project mcp-server-logs

📖 如需查看所有可用的命令行选项，请参阅“更多信息”部分中的命令行参考。

注意：此入口点没有 bearer 身份验证中间件。它使用单个服务端 WANDB_API_KEY，并拒绝绑定到非回环地址。

MCP 是 operator-wandb Helm chart 中的可选组件。升级前，请确认所选镜像和 chart 支持相同的运行时配置；只更改其中一项可能导致启动失败。请使用适用的版本化发行说明中的兼容性和不可变制品证据。

使用兼容的 chart 和镜像后，在 WeightsAndBiases values 中启用该组件：

mcp-server:
  install: true

启用后，可通过 https://<your-instance>/mcp 访问此服务。chart 会为客户端和面向用户的链接保留此公共 URL，同时将服务端 W&B API 调用路由到命名空间本地的 API 服务。

要求：

• 明确兼容 MCP 0.4 且已验证镜像摘要的 chart 版本。
• 适用于该安装的受支持工具配置和访问模式。
• 使用 models-weave 配置时，需安装并配置 Weave。models-only 配置不需要 Weave。

专用实例的客户端配置：

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

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

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'),
        },
    ],
    input="How many traces are in my-team/my-project?",
)

print(resp.output_text)