desktop-mcp

LLM을 위한 데스크톱 비전 및 제어 도구로, Wayland를 포함한 Linux에서 동작합니다 — 모델이 전체 화면을 스크린샷으로 캡처하고, 보이는 화면을 클릭하고 타이핑하고 스크롤합니다. stdio를 통한 일반 MCP이므로 Claude Code, Claude Desktop, Cursor 또는 다른 MCP 클라이언트에서도 동작합니다.

먼저 읽어보세요: 이 도구가 필요 없을 수도 있습니다

Anthropic은 computer use를 기본으로 제공하며, 이 기능이 동작하는 환경에서는 이 도구 대신 그것을 사용해야 합니다. 통합이 더 잘 되어 있고 실제로 유지관리되기 때문입니다:

• macOS 및 Windows: Claude Desktop에는 Cowork와 Claude Code에 computer use가 내장되어 있습니다. 실제 데스크톱을 제어합니다. (문서)

• 자체 에이전트 구축: Claude API에는 퍼스트파티 computer 도구가 있습니다 (computer_toolset_20260801 툴셋으로 GA). (문서)

이 도구가 메우는 공백은 Linux입니다. 2026년 8월 현재 computer use는 Linux 데스크톱 앱에서 사용할 수 없으며, Wayland에서의 데스크톱 자동화는 X11에서는 결코 없었던 방식으로 정말로 까다롭습니다:

• COSMIC의 컴포지터는 wlr-screencopy를 구현하지 않으므로 grim은 완전히 실패하며, 모든 스크린샷 도구는 컴포지터별 경로가 필요합니다.

• 커서 위치를 조회하는 프로토콜도, 다른 클라이언트의 창을 열거하는 프로토콜도 없습니다.

• 입력은 /dev/uinput을 통해 컴포지터 아래로 들어가야 합니다. 일반적으로 패키징된 ydotool은 상대 포인터를 노출하는데, 긴 점프는 포인터 가속에 의해 왜곡되기 때문입니다.

macOS 또는 Windows를 사용 중이라면 이 저장소는 대부분 중복입니다. Linux — 특히 Wayland — 를 사용 중이라면 이것이 실제로 동작하는 선택지입니다.

데스크톱 자동화 MCP 서버는 새로운 범주가 아닙니다. 수천 개의 MCP 서버가 있습니다. 여기서 특별한 점은 Wayland 네이티브 절대-uinput 입력 경로이며, COSMIC에서 픽셀 단위로 정확함이 측정되었다는 것입니다.

Related MCP server: mcp-linux-desktop

상태

크로스 플랫폼으로 작성되었지만 실제로 검증된 구성은 하나뿐입니다. 나머지는 코드 경로일 뿐 증거가 아닙니다 — 그에 맞게 취급하세요.

테스트된 내용과 방법

다음 환경에서 엔드투엔드로 검증했습니다:

• Pop!_OS 24.04 LTS, 커널 7.0.11, COSMIC (cosmic-comp 1.0.0), Wayland, 단일 2560x1440 디스플레이, Python 3.13.

결과:

테스트되지 않았고 알아둘 만한 사항: 다중 모니터 구성, HiDPI 배율, 원시 키코드 경로에서의 비US 키보드 레이아웃(wtype은 이를 올바르게 처리하지만 uinput 키코드는 US를 가정합니다), 그리고 COSMIC이 아닌 모든 컴포지터.

다른 플랫폼에서의 보고를 환영합니다 — desktop_info는 백엔드 문제를 진단하는 데 필요한 모든 것을 출력합니다.

설치

git clone <this repo> && cd desktop-mcp
uv venv && uv pip install -e .

macOS, Windows 및 Linux/X11에는 입력 의존성도 필요합니다:

uv pip install -e ".[gui]"

Linux: 1회성 권한 설정

Wayland에서 입력을 주입하려면 /dev/uinput에 쓰기가 필요하며, 기본적으로 이 파일의 소유자는 root입니다:

bash scripts/setup-linux.sh   # needs sudo once
# then log out and back in

macOS: 1회성 권한 설정

서버를 실행하는 앱(Terminal, iTerm, Claude Desktop)에 화면 기록 및 손쉬운 사용 권한을 System Settings → Privacy & Security에서 부여하세요.

연결하기

Claude Code:

claude mcp add desktop -- /absolute/path/to/desktop-mcp/.venv/bin/python -m desktop_mcp.server

Claude Desktop (claude_desktop_config.json) 및 Cursor (.cursor/mcp.json)도 동일한 형식을 사용합니다:

{
  "mcpServers": {
    "desktop": {
      "command": "/absolute/path/to/desktop-mcp/.venv/bin/python",
      "args": ["-m", "desktop_mcp.server"]
    }
  }
}

도구

좌표

스크린샷은 전송 전에 축소되며(기본적으로 긴 변 1400px), 따라서 모델은 이미지 픽셀 단위로 작업합니다. 서버는 모든 호출에서 이를 화면 픽셀로 다시 매핑합니다. 스크린샷에서 읽은 좌표를 그대로 전달하세요.

이것은 대부분의 자체 제작 computer-use 도구가 틀리는 세부 사항입니다. 이를 놓치면 모든 클릭이 목표 지점의 일정한 비율만큼 어긋난 위치에 떨어집니다.

Linux에서 ydotool 대신 /dev/uinput을 사용하는 이유

일반적으로 패키징된 ydotool 빌드는 상대 포인터를 노출하므로 (1280, 720)으로의 점프는 하나의 큰 상대 이동으로 전달되며, 컴포지터는 이를 포인터 가속에 통과시킵니다. 커서는 목표 지점 위가 아니라 근처에 도착하며, 오류는 거리에 따라 커집니다. 절대 uinput 장치는 가속을 우회합니다: 2560x1440 화면에서 5/5 정확함이 측정되었습니다. /dev/uinput에 쓸 수 없을 때 ydotool은 여전히 폴백으로 남아 있습니다.

클릭 타이밍

컴포지터는 포인터 이동을 비동기적으로 전달하며, 툴킷은 커서를 위젯 위에 놓은 이동을 처리하기 전에 도착한 버튼 누름을 무시합니다. COSMIC에서 측정한 결과: 이동과 누름 사이 30ms 간격은 버튼을 강조하기는 하지만 활성화하지는 않습니다 — 호버 상태는 좌표가 정확하다는 증거이므로, 이 실패를 타겟팅 버그로 오인하기 쉽습니다. 250ms면 활성화됩니다. 또한 누름은 오작동 이벤트가 아닌 실제 클릭으로 인식되도록 (~90ms) 동안 유지되어야 합니다.

두 지연 시간 모두 조정 가능합니다. 데스크톱이 허용하는 경우에만 낮추세요.

안전

이 도구는 모델에게 그 자리에 앉아 있는 사람과 동일한 수준의 시스템 접근 권한을 부여합니다. 화면의 모든 것을 읽을 수 있고 — 열려 있는 비밀번호 관리자, 개인 메시지, 토큰 — 파괴적인 버튼을 포함한 무엇이든 클릭할 수 있습니다. 세션을 마치 누군가에게 키보드를 건네준 것처럼 취급하세요.

환경 변수:

ctrl+alt+F1–F12는 항상 차단됩니다. VT 전환은 사용 중인 그래픽 세션을 갑자기 중단시킬 수 있습니다.

읽기 전용 검토자 설정:

DESKTOP_MCP_READ_ONLY=1 python -m desktop_mcp.server

검증

.venv/bin/python scripts/mcp_smoke.py   # real stdio MCP round trip