W&B MCP 서버에 액세스하기

IDE 또는 LLM 애플리케이션을 W&B Model Context Protocol(MCP) 서버에 연결해 에이전트가 사용자의 W&B 워크스페이스, 데이터, 그리고 W&B 문서에 접근할 수 있도록 합니다.

Model Context Protocol (MCP)는 LLM 에이전트가 토큰 사용 비용을 최소화하면서 데이터를 효율적으로 조회하고 분석할 수 있게 해줍니다. 이 페이지에서는 IDE 또는 MCP 클라이언트에서 W&B MCP 서버를 사용해 W&B 데이터를 조회·분석하는 방법과, 클라이언트가 W&B 관련 쿼리에 대해 더 정확한 응답을 생성할 수 있도록 W&B 문서에 대한 프로그래매틱 액세스를 제공하는 방법을 설명합니다.

MCP는 다음을 포함한 대부분의 IDE, 코딩 클라이언트, 채팅 에이전트와 기본적으로 통합됩니다:

• Cursor
• Visual Studio Code (VS Code)
• Claude Code
• Codex
• Gemini CLI
• Mistral LeChat
• Claude Desktop

W&B MCP 서버는 호스티드 및 로컬 버전을 지원합니다. 호스티드 버전은 W&B Dedicated Cloud 배포에서만 사용할 수 있습니다. 로컬 버전은 Dedicated Cloud와 Self-Managed 배포를 모두 지원합니다.

​

W&B MCP 서버 기능

MCP 서버를 사용해 실험을 분석하고, 트레이스를 디버깅하고, 리포트를 생성하고, 애플리케이션을 W&B 기능과 통합하는 데 도움을 받을 수 있습니다.

다음 예시 프롬프트는 MCP 서버에 연결되었을 때 에이전트가 수행할 수 있는 작업 유형을 보여줍니다:

• your-team-name/your-project-name에서 eval/accuracy 기준 상위 5개 runs를 보여 주세요.
• 지난 몇 달 동안 내 채용 에이전트의 예측 트레이스 지연 시간이 어떻게 변했는지 알려 주세요.
• 채용 에이전트가 지난달에 내린 결정들을 비교하는 wandb 리포트를 생성해 주세요.
• Weave에서 리더보드를 어떻게 만드는지 알려 주세요 - SupportBot에게 물어봐 주세요.

​

사용 가능한 도구

W&B MCP 서버는 에이전트가 다음 도구에 접근할 수 있게 해 줍니다:

Tool	설명	예시 쿼리
query_wandb_tool	W&B run, 메트릭, 실험을 조회합니다	”loss가 0.1보다 작은 run을 보여줘”
query_weave_traces_tool	LLM 트레이스와 평가를 분석합니다	”평균 레이턴시는 얼마야?“
count_weave_traces_tool	트레이스 개수를 세고 스토리지 메트릭을 조회합니다	”실패한 트레이스는 몇 개야?“
create_wandb_report_tool	프로그래밍 방식으로 W&B 리포트를 생성합니다	”성능 리포트를 생성해 줘”
query_wandb_entity_projects	엔티티의 프로젝트 목록을 조회합니다	”어떤 프로젝트들이 있어?“
query_wandb_support_bot	W&B 문서에서 도움을 받습니다	”스윕은 어떻게 사용해?”

​

W&B의 원격 MCP 서버 사용

W&B는 설치가 필요 없는 호스팅되는 MCP 서버 https://mcp.withwandb.com를 제공합니다. 다음 지침에서는 이 호스팅 서버를 다양한 AI 어시스턴트와 IDE에서 구성하는 방법을 설명합니다.

​

사전 준비 사항

• W&B Dedicated Cloud 배포 환경.
• W&B API 키. 새 API 키는 wandb.ai/authorize에서 생성할 수 있습니다.
• 키를 WANDB_API_KEY라는 이름의 환경 변수로 설정합니다.

​

MCP 클라이언트 구성

MCP 클라이언트 설정 방법이 안내된 탭을 선택하세요:

Cursor

원클릭 설치 링크를 사용해 Cursor에 W&B 서버를 자동으로 설치할 수 있습니다(Authorization 필드에 Bearer <your-wandb-api-key>를 추가해야 함). 또는 아래 지침에 따라 수동으로 설치할 수 있습니다:

1. macOS에서는 Cursor 메뉴를 열고 Settings를 선택한 다음 Cursor Settings를 선택합니다. Windows 또는 Linux에서는 Preferences 메뉴를 열고 Settings를 선택한 다음 Cursor Settings를 선택합니다.
2. Cursor Settings 메뉴에서 Tools and MCP를 선택합니다. 그러면 Tools 메뉴가 열립니다.
3. Installed MCP Servers 섹션에서 Add Custom MCP를 선택합니다. 그러면 mcp.json 설정 파일이 열립니다.
4. 설정 파일의 mcpServers JSON 객체에 다음 wandb 객체를 추가합니다:

{
  "mcpServers": {
    "wandb": {
      "transport": "http",
      "url": "https://mcp.withwandb.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-wandb-api-key>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

5. 변경 사항이 적용되도록 Cursor를 재시작합니다.
6. 채팅 에이전트가 W&B MCP 서버에 액세스할 수 있는지 확인하려면 프롬프트로 “내 W&B 계정의 Projects를 나열해 줘.”를 입력합니다.

자세한 정보는 Cursor의 문서를 참고하세요.

Claude Code

W&B MCP 서버를 Claude Code에 추가하려면, 다음 명령의 Authorization 헤더에 본인의 W&B API 키를 설정한 뒤 터미널에서 실행하세요:

claude mcp add --transport http wandb https://mcp.withwandb.com/mcp \
  --header "Authorization: Bearer <your-wandb-api-key>"

전역 설정을 적용하려면 --scope user를 추가하고, 현재 프로젝트에만 설정하려면 이를 생략하세요.

더 자세한 내용은 Claude Code의 문서를 참조하세요.

Codex

Codex에 W&B MCP 서버를 추가하려면, 다음 명령의 --bearer-token-env-var 인수를 W&B API 키가 포함된 환경 변수로 설정한 뒤 터미널에서 실행하세요:

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

OpenAI

OpenAI 호출에서 W&B MCP 서버를 사용하려면 OpenAI 응답 설정의 tools 필드에 해당 서버의 정보를 추가하세요:

from openai import OpenAI
import os

client = OpenAI()

resp = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_label": "wandb",
        "server_description": "Query W&B data",
        "server_url": "https://mcp.withwandb.com/mcp",
        "authorization": os.getenv("<your-wandb-api-key>"),
        "require_approval": "never",
    }],
    input="List the projects in my W&B account.",
)

print(resp.output_text)

Gemini CLI

Gemini CLI에 W&B MCP 서버를 추가하려면:

1. 다음 명령 하나로 W&B MCP 확장을 설치합니다:

   # 확장 설치
   gemini extensions install https://github.com/wandb/wandb-mcp-server
   

2. 설치가 완료되면 Gemini CLI를 다시 시작합니다.

3. 채팅 에이전트가 W&B MCP 서버에 액세스할 수 있는지 확인하려면 프롬프트에 “List the projects in my W&B account.”를 입력합니다.

자세한 내용은 Gemini 문서를 참고하세요.

Mistral LeChat

Mistral LeChat에 W&B MCP 서버를 추가하려면:

1. Intelligence 메뉴에서 Add Connector를 선택하여 Connector 창을 엽니다.

2. Custom MCP Connector 탭을 선택합니다.

3. 다음 값으로 필드를 설정합니다:

   • Connector Server: https://mcp.withwandb.com/mcp
   • Description: (선택 사항) 연결에 대한 간단한 설명을 입력합니다.
   • Authentication Method: API Token Authentication을 선택합니다. 그러면 추가 필드가 열립니다.
   • Header name: 기본값인 Authorization을 그대로 둡니다.
   • Header type: Bearer를 선택합니다.
   • Header value: 본인의 W&B API 토큰을 입력합니다.

4. 모든 필드 설정을 마쳤으면 Create를 선택합니다. 그러면 LeChat이 MCP 서버를 사용자의 설정에 추가합니다.

5. 채팅 에이전트가 W&B MCP 서버에 액세스할 수 있는지 확인하려면 프롬프트 “List the projects in my W&B account.”를 입력합니다.

더 자세한 내용은 LeChat 문서를 참조하세요.

​

로컬 버전 W&B MCP 서버 설정

W&B Self-Managed 배포, 개발, 테스트 또는 망 분리(air-gapped) 환경에서 MCP 서버를 로컬에서 실행해야 하는 경우, 로컬 머신에 MCP 서버를 설치하고 실행할 수 있습니다.

​

사전 준비 사항

• W&B API 키. wandb.ai/authorize에서 새 키를 생성할 수 있습니다.
• 환경 변수 WANDB_API_KEY에 이 키를 설정합니다.
• W&B Self-Managed를 사용하는 경우 WANDB_BASE_URL 환경 변수를 설정합니다.
• Python 3.10 이상
• uv (권장) 또는 pip

설치 방법은 uv 문서의 설치 안내를 참고하세요.

​

MCP 서버 설치 및 설정

MCP 서버를 로컬에 설치하려면:

로컬 머신에 W&B MCP 서버를 설치하려면 다음 설치 명령 중 하나를 사용하세요:

uv

uv install wandb-mcp-server

pip

pip install wandb-mcp-server

Install directly from GitHub

pip install git+https://github.com/wandb/wandb-mcp-server

MCP 서버를 로컬에 설치한 후에는 MCP 클라이언트를 이 서버를 사용하도록 설정해야 합니다. 계속하려면 MCP 클라이언트를 선택하세요:

Cursor

mcp.json 설정에 다음 내용을 추가하세요:

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

VS Code

.vscode/mcp.json 또는 전역 MCP 설정에 다음 내용을 추가하세요:

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

Claude Code

터미널에서 다음 명령을 실행하세요. 전역 설정을 위해서는 --scope user를 추가하고, 현재 프로젝트에만 설정하려면 이를 생략하세요.

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

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 Desktop

텍스트 편집기에서 Claude 설정 파일을 여세요. 운영체제별 설정 파일 위치는 다음과 같습니다:

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

Claude 설정 파일의 JSON 객체에 다음 내용을 추가하세요. Claude Desktop이 uvx 설치 위치를 찾지 못할 수 있으므로, uvx의 전체 경로를 사용하세요.

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

새 설정을 적용하려면 Claude Desktop을 다시 시작하세요.

웹 기반 클라이언트 또는 테스트용으로는 HTTP 전송을 사용하여 서버를 실행하세요:

uvx wandb_mcp_server --transport http --host 0.0.0.0 --port 8080

외부 클라이언트(예: OpenAI)에서 접근할 수 있도록 로컬 서버를 공개하려면 ngrok을 사용하세요:

uvx wandb_mcp_server --transport http --port 8080

# 다른 터미널에서 ngrok으로 외부에 노출
ngrok http 8080

서버를 ngrok으로 공개하는 경우 MCP 클라이언트 설정을 ngrok URL을 사용하도록 업데이트하세요.

​

사용 팁

• W&B 프로젝트와 Entity 이름을 제공하세요: 정확한 결과를 위해 쿼리에서 W&B Entity와 프로젝트를 명시하세요.
• 너무 포괄적인 질문은 피하세요: “what is my best evaluation?” 대신 “what eval had the highest f1 score?”와 같이 질문하세요.
• 데이터 조회 결과를 확인하세요: “what are my best performing runs?”처럼 포괄적인 질문을 할 때는, 사용 가능한 모든 run을 가져왔는지 어시스턴트에게 확인해 달라고 요청하세요.