🖥️ screen-use

browser-use, 하지만 전체 데스크톱용.

Windows에서 모든 AI 에이전트에게 눈 👀과 손 🖐️을 부여하세요 — Claude, Kimi, Cursor 또는 자신의 에이전트가 화면을 보고, UI 요소를 찾고, 자연어를 통해 모든 데스크톱 앱을 조작할 수 있게 합니다. 셀렉터가 필요 없습니다. UI가 변경되면 깨지는 스크립트도 없습니다.

👆 앱 간 자율성: 에이전트가 계산기에서 결과를 읽고, 메모장을 활성화하고, 결과를 입력합니다 — 모든 단계는 화면을 보는 VLM이 결정합니다 (하단의 실시간 사고 스트림 참조).

단일 앱 에이전트 루프 (VLM이 78 × 9를 스스로 계산):

스크립트 기반 앱 간 작업 (계산기 → 메모장):

단일 앱 정밀 클릭:

왜 필요한가

전통적인 RPA는 셀렉터를 기록하지만 — 페이지가 변경되는 순간 깨집니다. browser-use (32k⭐)는 브라우저에서 이 문제를 해결했습니다. screen-use는 동일한 아이디어를 전체 데스크톱으로 확장합니다: Excel, SAP 클라이언트, ERP 소프트웨어, 심지어 레거시 Win32 프로그램까지.

Related MCP server: WinPilot Computer Use MCP

작동 방식

Your Agent (Claude / Kimi / Cursor / custom)   ← does the planning
        │  MCP or Python SDK
        ▼
┌─────────────────────────────────────────────┐
│ screen-use                                  │
│  Visual Loop ──► observe→think→act→verify   │
│  Introspection──► difficulty playbook        │
│  Meta-learning──► experience & vocab memory  │
│  Perception ──► UIA tree + screenshots (SoM)│
│  Locating   ──► strategy chain:             │
│                 ⓪ learned vocab mapping     │
│                 ① UIA text match (0 cost)   │
│                 ② Set-of-Mark + VLM         │
│  Action     ──► mouse / keyboard            │
└─────────────────────────────────────────────┘

VLM은 선택 사항이며 필수가 아닙니다. 위치 찾기 전략 체인은 순수 접근성 트리 텍스트 매칭으로 대부분의 대상을 찾습니다 — 모델 호출 없음, 밀리초 지연 시간. 비전 모델(클라우드 또는 Ollama를 통한 로컬)은 UIA가 보이지 않는 UI에서만 작동합니다.

빠른 시작

git clone https://github.com/tongriyaotxt/screen-use.git
cd screen-use
pip install -r requirements.txt

Kimi CLI 플러그인으로 사용 (권장)

한 줄 명령 — Kimi가 즉시 14개의 데스크톱 도구를 모두 사용할 수 있습니다:

kimi mcp add --transport stdio screen-use -- <path-to-python.exe> -m screen_use.mcp_server
kimi mcp test screen-use   # verify the connection

선택적으로 번들된 사용 전략 스킬을 설치하면, Kimi에게 최적의 도구 선택 플레이북을 가르칩니다:

mkdir -p ~/.kimi/skills/screen-use && cp skills/screen-use/SKILL.md ~/.kimi/skills/screen-use/

그런 다음 Kimi에게 말하기만 하면 됩니다: "계산기를 열고 123 × 456을 계산해" 또는 "내 메모장에 뭐가 있는지 읽어줘".

일반 MCP 서버로 사용

claude_desktop_config.json (또는 MCP 호환 에이전트의 설정)에 추가하세요:

{
  "mcpServers": {
    "screen-use": {
      "command": "python",
      "args": ["-m", "screen_use.mcp_server"],
      "cwd": "path/to/screen-use"
    }
  }
}

그런 다음 에이전트에게 말하기만 하면 됩니다: "계산기를 열고 123 × 456을 계산해."

Python SDK로 사용

from screen_use import ScreenUse

tools = ScreenUse()

tools.click_element("Save")            # locate + click, one call
tools.type_text("Hello, 你好")          # Unicode-safe (clipboard paste)
tools.hotkey("ctrl", "s")

# Atomic tools for vision-capable agents:
elements = tools.list_ui_elements()    # id, name, type, bbox — no model needed
shot = tools.screenshot(annotate=True) # Set-of-Mark annotated screenshot
tools.click(500, 300)

자율 작업 루프

한 번의 호출로 완전한 자율성 — 에이전트가 보고, 결정하고, 행동하고, 스스로 수정합니다:

tools.run_task("打开计算器，算 25 乘以 4")   # observe → think → act → verify

자기 성찰 (난이도 분류 성찰): 루프가 막히면, 난이도를 분류합니다 — 효과 없음 / 루프 반복 / 연속 실패 / 요소 누락 / 예상치 못한 팝업 — 그리고 대상화된 프롬프트 플레이북으로 성찰한 후 전략을 조정합니다.

메타 러닝 (메타 학습): 성공한 실행이 기억됩니다. 유사한 과거 작업이 경험 힌트로 회상되고, 학습된 어휘 매핑(예: "곱셈 기호" → Multiply by)이 전략 체인의 새로운 첫 번째 레벨이 됩니다. 사용할수록 실제로 더 좋아집니다. 메모리는 ~/.screen_use/에 저장됩니다.

도구 (14개)

원자적 도구 (모델 의존성 없음): screenshot · list_ui_elements · click · double_click · right_click · click_element_id · type_text · hotkey · press · scroll

고수준 도구: find_element (전략 체인 위치 찾기) · click_element (위치 찾기 + 클릭) · read_screen (VLM 화면 Q&A) · run_task (자율 비주얼 루프)

비전 모델 (선택 사항)

에이전트에 비전이 없고 대상 앱이 UIA를 지원하지 않는 경우에만 필요합니다. .env.example을 .env로 복사하세요:

VLM을 구성하지 않아도 원자적 도구와 UIA 매칭은 완전히 작동합니다.

안전

• 🚨 안전 장치: 마우스를 왼쪽 상단 모서리로 밀어 즉시 중단

• ✅ 모든 작업을 승인하는 confirm_callback 훅 (SDK)

• 🧪 ScreenUse(dry_run=True)는 실행 없이 작업을 기록합니다

확장성

screen-use는 교체 가능한 레이어 집합으로 설계되었습니다 — 핵심을 건드리지 않고 모든 계층을 확장할 수 있습니다:

안전 훅도 인터페이스의 일부입니다: 인간 개입 승인을 위한 confirm_callback, 시뮬레이션을 위한 dry_run, 비상 정지를 위한 PyAutoGUI 안전 장치.

로드맵

• UIA + SoM 위치 찾기 전략 체인

• MCP 서버 (14개 도구)

• 로컬 VLM 지원 (Ollama)

• 자율 비주얼 루프 (run_task)

• 자기 성찰 플레이북 및 메타 러닝 메모리

• wait_for_element / 자동 검증 프리미티브

• 드래그 앤 드롭

• VLM 원시 좌표 폴백 + OpenCV 템플릿 매칭 (UIA 미지원 앱)

• macOS (접근성 API) 및 Linux 지원

• PyPI 릴리스

기여를 환영합니다 — 좋은 첫 작업은 issues를 확인하세요.

개발

pytest tests -q                        # 61 unit tests, no desktop/VLM needed
python examples/demo_calculator.py     # end-to-end demo (real clicks!)
python examples/mcp_client_demo.py     # MCP handshake + tool list

라이선스

MIT

screen-use = 데스크톱 버전 browser-use: 모든 AI 에이전트가 화면을 보고 데스크톱 앱을 조작할 수 있는 능력을 부여합니다.

• 전통적인 RPA가 아님: 셀렉터를 기록하지 않고, 접근성 트리 + 비전 모델로 UI를 이해하므로 인터페이스가 변경되어도 걱정 없음

• 모든 데스크톱 앱 지원: Excel, SAP, ERP 클라이언트, 레거시 Win32 프로그램

• 자연어 구동: click_element("저장 버튼") 한 마디로 해결

• VLM 선택 사항: 전략 체인의 첫 번째 레벨은 순수 UIA 텍스트 매칭 (모델 없음, 밀리초), 비전 모델은 맹점에서만 보완, 로컬 Ollama 지원으로 개인정보 보호

연결 방식, 도구 목록, 안전 구성은 위의 영문 버전과 동일합니다.