desktop-control-mcp

두 가지 인터페이스를 통해 마우스, 키보드, 화면 캡처, AI 기반 UI 요소 감지를 제공하는 Windows 데스크톱 자동화 서버입니다:

• MCP 서버 (mcp_server.py) — stdio 전송 방식으로, Claude Code, Claude Desktop 및 기타 MCP 클라이언트와 함께 사용하도록 설계되었습니다

• HTTP 서버 (server.py + app.py) — http://localhost:7845에서 실행되는 Flask API로, 시스템 트레이 아이콘에서 실행할 수 있습니다

두 인터페이스는 동일한 기본 controller.py(Windows 자동화)와 ui_parser.py(비전 모델)를 공유하므로 기능은 동일합니다.

주요 기능

• AI 비전 기반 클릭 — UI 요소는 Microsoft OmniParser v2 (YOLO 아이콘 감지기 + Florence-2 캡셔너 + EasyOCR)로 감지되므로, 스크린샷에서 픽셀 좌표를 추측하는 대신 의도에 따라 버튼/필드를 대상으로 지정할 수 있습니다.

• DPI 인식 — PROCESS_PER_MONITOR_DPI_AWARE로 실행되므로 Windows 디스플레이 배율과 관계없이 좌표는 항상 물리적 픽셀입니다.

• 스크린샷의 커서 — 실제 Windows 커서 비트맵이 Win32 GDI API를 통해 모든 스크린샷에 합성되므로 AI 클라이언트가 마우스 위치를 볼 수 있습니다.

• 세 가지 스크린샷 모드 — 단일 압축 JPEG, 주석이 있는 감지 뷰, 시간 분산 버스트 캡처(애니메이션 또는 로딩 상태 관찰용).

• 스마트 키보드 디스패치 — 리터럴 텍스트, 단일 키, 수정자 조합을 위한 별도 도구가 있어 "ctrl+c"가 실수로 텍스트로 입력되지 않습니다.

Related MCP server: desktop-automation-mcp

설치

Windows 및 Python 3.10+가 필요합니다.

git clone https://github.com/ahmetdenizyilmaz/desktop-control-mcp.git
cd desktop-control-mcp
pip install -r requirements.txt

첫 실행 시 OmniParser v2 모델 가중치(약 1GB)가 Hugging Face에서 로컬 캐시로 다운로드됩니다. CUDA 지원 PyTorch가 설치된 경우 GPU가 자동으로 사용되고, 그렇지 않으면 CPU가 사용됩니다.

실행

MCP 서버(stdio)로

MCP 클라이언트 설정(예: Claude Desktop / Claude Code)에 다음과 같은 항목을 추가하세요:

{
  "mcpServers": {
    "desktop-control": {
      "command": "python",
      "args": ["C:\\path\\to\\desktop-control-mcp\\mcp_server.py"]
    }
  }
}

서버는 즉시 부팅됩니다. 모델은 백그라운드 스레드에서 로드되므로 첫 detect_ui_elements 호출은 모델을 기다리지만 나머지 도구는 바로 사용할 수 있습니다.

트레이 아이콘이 있는 HTTP 서버로

python app.py

Start / Stop / Quit 옵션이 있는 트레이 아이콘이 나타납니다. Flask API는 http://localhost:7845에서 수신 대기합니다. 엔드포인트 세부 정보는 API_DOCS.md를 참조하세요.

MCP 도구

화면 정보

스크린샷

마우스

키보드

필수 클릭 워크플로우

좌표는 화면 변경 시 안정적이지 않습니다. 모든 메뉴가 열리고, 모든 대화 상자가 나타나고, 모든 스크롤이 요소를 이동시킵니다. 서버는 다음 루프를 강제합니다:

1. 감지 — detect_ui_elements가 현재 요소 테이블을 반환합니다.

2. 찾기 — Label 열에서 대상을 일치시킵니다.

3. 클릭 — 테이블의 정확한 Center 좌표를 사용하여 click_mouse(x, y)를 실행합니다.

4. 확인 — 클릭이 적용되었는지 take_screenshot로 확인합니다.

5. 복구 — 클릭이 빗나간 경우 다시 감지(화면이 변경되었을 수 있음)하고 재시도합니다.

원시 스크린샷에서 좌표를 추측하지 마세요. detect_ui_elements의 요소 테이블이 진실의 원천입니다.

요소 테이블 예시

  ID  Type   Conf   Center         Label
   1  text   0.98   ( 499,   55)   File  Edit  View
   2  icon   0.91   ( 674,  200)   Search button
   3  icon   0.87   (1200,  400)   Close

검색 버튼을 클릭하려면: click_mouse(x=674, y=200).

HTTP API

app.py로 실행하면 포트 7845의 Flask 서버가 MCP 도구를 미러링합니다:

전체 요청/응답 스키마는 API_DOCS.md에 있습니다.

파일 구성

mcp_server.py          FastMCP server — tool definitions and lifespan
controller.py          Win32 / pyautogui / mss core — screenshots, input, window info
ui_parser.py           OmniParser v2 loading + UI detection + image annotation
screenshot_manager.py  Disk-side screenshot cache (cleanup, naming, burst dirs)
overlay.py             On-screen overlay utilities
lock_manager.py        Concurrency lock for shared resources
server.py              Flask HTTP API
app.py                 Tray-icon launcher for the Flask server
templates/index.html   Web UI for the Flask server
requirements.txt       Python dependencies
API_DOCS.md            HTTP endpoint reference
run_agents.bat         Convenience launcher for Claude Code in this folder

플랫폼 참고 사항

• Windows 전용. 커서 합성, DPI 인식 및 활성 창 코드는 Win32 API를 직접 사용합니다.

• 기본 모니터만 지원. 모든 좌표는 기본 모니터의 픽셀 공간에 있습니다.

• 첫 감지는 느립니다. OmniParser 모델 로드 + EasyOCR 초기화는 첫 호출 시 30~60초가 걸릴 수 있습니다. 이후 감지는 빠릅니다(GPU에서 1초 미만, CPU에서 몇 초).