Skip to main content
Glama
desktop-control-mcp

desktop-control-mcp

desktop-control-mcp

Claude Desktop Controller 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 도구

화면 정보

도구

설명

get_screen_size()

기본 모니터 해상도. 좌표 공간을 파악하려면 한 번 호출하세요.

get_active_window()

현재 포커스된 창의 제목, 위치 및 크기.

스크린샷

도구

설명

take_screenshot(quality=30)

기본 모니터의 압축 JPEG. 관찰 전용입니다. 여기서 좌표를 유도하지 마세요.

detect_ui_elements(confidence_threshold=0.5, full_response=False)

OmniParser + EasyOCR을 실행하고, 감지된 모든 요소에 대해 주석이 있는 이미지와 (id, type, confidence, center, label) 테이블을 반환합니다. 이것이 클릭할 좌표를 찾는 방법입니다.

take_screenshot_burst(frame_count=10, duration_seconds=1.0)

주어진 시간에 고르게 분산된 N개의 프레임을 캡처합니다. 애니메이션, 로딩 스피너 또는 타이밍에 민감한 UI에 유용합니다.

마우스

도구

설명

click_mouse(x, y, button="left")

단일 클릭. 항상 detect_ui_elements의 좌표를 사용하세요.

double_click(x, y)

더블 클릭.

move_mouse(x, y)

클릭 없이 커서 이동.

drag_mouse(x1, y1, x2, y2, button="left")

클릭 앤 드래그.

scroll(x, y, direction, amount=3)

위치에서 휠 스크롤 (up/down/left/right).

키보드

도구

사용 시기

type_text(text)

일반 텍스트 입력(파일 이름, 검색어, URL, 코드). +를 단축키로 해석하지 않습니다.

press_key(key, presses=1)

단일 이름 키 (enter, tab, escape, f5, 화살표 키, delete 등).

send_keys(text)

수정자+키 조합 전용 (ctrl+c, alt+tab, win+d, ctrl+shift+s).


필수 클릭 워크플로우

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

  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 도구를 미러링합니다:

엔드포인트

설명

GET /health

활성 상태 확인.

POST /screenshot

화면의 base64 PNG를 반환합니다.

POST /move

{x, y} — 커서 이동.

POST /click

{x, y, button?} — 클릭.

POST /keys

{keys} — 텍스트 또는 단축키(자동 감지).

POST /command

[ClickMouse(500,300)] 같은 단일 대괄호 명령.

POST /actions

선택적 delay를 두고 순차적으로 실행되는 대괄호 명령 목록.

전체 요청/응답 스키마는 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에서 몇 초).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that provides computer control capabilities including mouse movements, keyboard actions, screenshot capture with OCR, and window management through a unified API.
      549 PyPI
      176
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for driving any Windows app through five layers including OCR, UI Automation, and direct OS operations. Enables AI agents to control Windows desktop and OS cursor-free, even on background/locked windows.
      122 npm
      3
      MIT