winuse-mcp

Windows에서 Claude Code를 위한 컴퓨터 사용. Claude가 화면을 보고 마우스와 키보드를 제어할 수 있게 해주는 MCP 서버입니다.

Claude Code는 macOS에서만 CLI로 컴퓨터 사용 기능을 제공하므로, Windows에서는 /mcp에 computer-use 서버가 나타나지 않습니다. 이 프로젝트는 Windows API를 사용하여 동일한 스크린샷-클릭 루프를 재구성합니다: 14개의 도구, 5개의 종속성, Python 3.12.

설치

Windows와 uv가 필요합니다. 프로젝트의 .mcp.json에 추가하거나, 모든 프로젝트에 적용하려면 ~/.claude.json에 추가하세요:

{
  "mcpServers": {
    "winuse": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ryanportfolio/winuse-mcp", "winuse-mcp"]
    }
  }
}

로컬 클론에서 사용하려면:

{
  "mcpServers": {
    "winuse": {
      "command": "uv",
      "args": ["run", "--directory", "C:/path/to/winuse-mcp", "winuse-mcp"]
    }
  }
}

Claude Code를 다시 시작한 다음, 화면을 보거나 앱을 클릭하도록 요청하세요.

Related MCP server: Win:Computer Use

기능

좌표는 항상 스크린샷 공간 기준입니다. 아래 참조.

좌표 작동 방식

스크린샷은 긴 쪽이 최대 1372픽셀이 되도록 축소됩니다. 이는 Claude Code가 macOS에서 사용하는 동일한 목표값입니다. Claude는 기본 픽셀을 볼 수 없으므로 축소된 이미지에서 클릭하고 서버가 다시 변환합니다.

1920x1080 디스플레이는 1372x772로 캡처되며, 비율은 0.715입니다. 686, 443에서의 클릭은 960, 620에 도달합니다.

서버는 시작 시 DPI 인식으로 선언되므로, 125% 또는 150%의 Windows 디스플레이 배율이 클릭 위치를 왜곡하지 않습니다.

안전

이 도구는 언어 모델이 데스크톱을 제어할 수 있게 합니다. Anthropic의 자체 버전은 이 서버에는 없는 보호 장치로 동일한 루프를 감쌉니다: 앱별 승인, Claude가 승인되지 않은 앱 숨기기, 터미널을 스크린샷에서 제외, 각 동작에 대한 모델 측 검사.

제공되는 기능:

• 허용 목록에 추가하지 않는 한 Claude Code는 각 도구 호출 전에 확인을 요청합니다. 입력 도구는 수동 승인으로 유지하고 screenshot만 허용 목록에 추가하세요.

• 마우스를 화면 왼쪽 상단 모서리에 두면 진행 중인 동작을 중단할 수 있습니다. 이는 pyautogui의 안전 장치이며, 해당 모서리만 감시합니다. 드래그 중에 중단하면 마우스 버튼이 해제되므로 드래그 상태가 남지 않습니다.

• 화면에 보이는 모든 것이 모델에 전달됩니다. 화면의 텍스트는 신뢰할 수 없는 입력입니다: 화면에 나타나는 지침은 프롬프트 인젝션 위험으로 간주하세요.

제한 사항

• 기본 모니터만 지원합니다.

• 터미널이 스크린샷에서 제외되지 않으므로 Claude가 자신의 세션을 볼 수 있습니다.

• record는 최대 8개의 정지 프레임을 샘플링합니다. 비디오 경로는 없습니다.

개발

uv sync
uv run winuse-mcp

scripts/client_test.py는 참조 검사입니다: stdio를 통해 서버와 MCP로 통신하고, 도구를 나열하고, 스크린샷을 찍고, 마우스를 이동하고 위치를 다시 읽고, 프레임을 기록하고, 잘못된 키 조합이 오류를 발생시키는지 확인합니다.

uv run python scripts/client_test.py

scripts/failsafe_test.py는 사용자가 중단할 때 발생하는 경로를 다룹니다. pyautogui가 스텁 처리되어 실제 중단이 필요하지 않습니다: 짧게 끝난 드래그는 여전히 버튼을 해제하고, 짧게 끝난 가로 스크롤은 여전히 shift를 해제하며, 코드 구문 분석은 리터럴 +를 처리하고, 어떤 클릭도 안전 장치 픽셀에 도달하지 않습니다.

uv run python scripts/failsafe_test.py

이 README는 빌드됩니다. 페이지의 모든 숫자는 빌드 시 소스에서 다시 계산되며, 하나라도 어긋나면 빌드가 실패합니다.

node scripts/readme/build.mjs

라이선스

MIT