uitars-mcp

AI 코딩 에이전트에게 로컬 GUI 그라운딩 기능을 제공하는 MCP 서버입니다. 화면상의 모든 UI 요소를 찾아 정확한 픽셀 좌표를 반환할 수 있습니다.

ByteDance의 2B 파라미터 GUI 그라운딩 모델인 UI-TARS-2B로 구동됩니다.

목적

Claude Code의 내장 컴퓨터 사용 기능은 분석을 위해 모든 스크린샷을 클라우드로 전송합니다. 이 MCP 서버는 대신 로컬 비전 모델을 실행합니다:

• 요소당 약 1.2초 탐색 (클라우드 왕복 지연 시간 대비)

• 4.1GB VRAM (최신 GPU에서 실행 가능)

• 완전 오프라인 — API 키나 클라우드 의존성 없음

• 90.7% 정확도 (ScreenSpot 데스크톱 텍스트 벤치마크 기준)

• 네이티브 픽셀 좌표 — 정확한 클릭 대상 반환

설정

1. UI-TARS-2B 다운로드

# Requires ~4.5GB disk space
huggingface-cli download bytedance-research/UI-TARS-2B-SFT --local-dir ./ui-tars-2b

2. CUDA가 포함된 PyTorch 설치

# Install CUDA-enabled PyTorch first (adjust cu126 to your CUDA version)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

3. uitars-mcp 설치

pip install uitars-mcp
# or from source:
pip install -e .

4. Claude Code 구성

Claude Code MCP 설정(~/.claude/settings.json)에 추가하세요:

{
  "mcpServers": {
    "uitars-mcp": {
      "command": "uitars-mcp",
      "env": {
        "UITARS_MODEL": "/path/to/ui-tars-2b"
      }
    }
  }
}

venv에 설치된 경우, 실행 파일의 전체 경로를 사용하세요:

{
  "mcpServers": {
    "uitars-mcp": {
      "command": "/path/to/venv/bin/uitars-mcp",
      "env": {
        "UITARS_MODEL": "/path/to/ui-tars-2b"
      }
    }
  }
}

도구

작동 원리

1. mss를 통해 스크린샷 촬영 (빠르고 플랫폼 독립적)

2. 1344px 너비로 크기 조정 (최적의 비전 토큰 수)

3. GPU에서 UI-TARS-2B 추론 실행

4. 모델의 0-1000 정규화 좌표를 네이티브 화면 픽셀로 변환

5. computer-use 클릭 도구에 바로 사용할 수 있는 좌표 반환

모델은 첫 호출 시 지연 로딩되며(약 3초), 이후 후속 호출을 위해 VRAM에 상주합니다.

환경 변수

요구 사항

• Python 3.10+

• 4.1GB 이상의 VRAM을 갖춘 NVIDIA GPU

• CUDA 지원 PyTorch

• Windows 또는 Linux (macOS는 테스트되지 않음)