Windows-MCP 딥다이브
— LLM 에이전트에게 "윈도우를 손에 쥐어주는" MCP 서버

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

핵심은 "비전 모델 없이도 화면을 이해한다"는 점이다. 보통 컴퓨터 자동화는 화면을 이미지로 캡처해 픽셀을 분석(OCR·객체탐지)하지만, Windows-MCP는 윈도우가 내부적으로 들고 있는 접근성 트리(UI Automation tree)를 읽어 "여기 버튼이 있고, 이름은 저장, 좌표는 (820,540)"처럼 구조화된 텍스트로 화면을 파악한다. 그래서 가볍고, 어떤 LLM과도 붙는다.

2왜 주목받는가

왜 Claude Desktop 확장 2M+ 사용자를 모으고 트렌딩에 오르는가.

2024~2026년은 "에이전트가 실제로 컴퓨터를 조작한다"는 흐름(Computer Use)이 폭발한 시기다. 맥/리눅스용 컴퓨터 제어 도구는 여럿 나왔지만, 압도적 점유율의 윈도우를 정식으로, 그리고 가볍게 다루는 MCP 서버는 드물었다. 이 레포가 트렌딩에 오르는 이유는 다음과 같다.

3기술 스택 전체 지도

이 서버를 떠받치는 기술을 역할별로 분해했다.

Windows-MCP는 순수 Python 3.13+ 단일 패키지다. 별도 프론트엔드는 없고(클라이언트가 곧 UI), 대신 윈도우 네이티브 API를 파이썬에서 호출하는 얇은 레이어가 핵심이다.

핵심 라이브러리 3종 빠르게 짚기

4아키텍처 심화 — MCP 클라이언트↔서버↔윈도우 제어

AI의 명령이 어떤 길을 거쳐 실제 클릭이 되는가.

전체 흐름은 3단(클라이언트 → MCP 서버 → 윈도우 OS)으로 나뉜다. 클라이언트(예: Claude Desktop)는 LLM과 사용자를 들고 있고, 그 안의 LLM이 "어떤 도구를 어떤 인자로 호출할지"를 결정한다. 결정된 호출은 MCP 프로토콜로 Windows-MCP 서버에 전달되고, 서버가 윈도우 API로 실제 동작을 수행한 뒤 결과(텍스트/스크린샷)를 되돌려준다.

핵심 설계 패턴 3가지

# tools/input.py — Click 도구의 핵심 (발췌·요약)
def click_tool(loc=None, label=None, button="left", clicks=1):
    if label is not None:
        loc = desktop.get_coordinates_from_label(label)  # 번호→좌표
    x, y = loc
    desktop.click(loc=loc, button=button, clicks=clicks)
    return f"{button} clicked at ({x},{y})."

5디렉토리 구조 해부

기능별로 잘 쪼개진 패키지. 도구 정의와 실제 실행이 분리돼 있다.

핵심은 src/windows_mcp/ 아래다. tools/는 MCP 도구의 "정의·검증·설명"을, 각 기능 디렉토리(desktop·powershell·registry…)는 "실제 윈도우 작업"을 담당하는 정의/실행 분리 구조다.

읽는 순서 추천: ① pyproject.toml로 의존성·진입점 파악 → ② tools/input.py로 도구가 어떻게 정의되는지(데코레이터·인자 검증) → ③ desktop/service.py로 실제 클릭/타이핑 구현 → ④ tree/·uia/로 접근성 트리를 label로 바꾸는 마법을 본다.

6학습 포인트 (기술별)

이 레포를 거치며 실제로 손에 남기면 좋은 것들.

MCP 서버 만드는 법 — 가장 큰 수확

Windows-MCP는 "잘 만든 FastMCP 서버"의 교과서다. 핵심은 함수 하나 = 도구 하나라는 패턴과, LLM이 잘 이해하도록 description을 꼼꼼히 적는 것이다. 아래는 이 레포가 도구를 등록하는 실제 형태다.

# tools/input.py — FastMCP 도구 등록 패턴 (요약)
@mcp.tool(
    name="Click",
    description=(
        "Performs mouse clicks at coordinates [x, y] or a UI element's label. "
        "button: 'left'/'right'/'middle'. clicks: 0=hover,1=single,2=double."
    ),
    annotations=ToolAnnotations(
        title="Click",
        readOnlyHint=False,        # 화면을 바꾸는 동작인가
        destructiveHint=True,      # 되돌릴 수 없을 수 있음
        idempotentHint=False,      # 여러 번 호출하면 결과가 달라짐
    ),
)
def click_tool(loc=None, label=None, button="left", clicks=1):
    ...

여기서 배울 핵심: ① description은 LLM을 위한 사용설명서(인자 의미를 자연어로), ② ToolAnnotations로 도구의 위험도/멱등성을 메타데이터로 표시, ③ register() 함수로 의존성(get_desktop 등)을 주입받는 깔끔한 구조.

윈도우 접근성 트리(UIA) — 화면을 코드로 다루기

"비전 없이 화면을 이해한다"의 정체가 바로 UIA다. 윈도우의 모든 창·컨트롤은 트리로 노출되며, 각 노드는 name·control_type·좌표·focus 여부 같은 메타데이터를 갖는다. Windows-MCP는 이 트리를 순회해 상호작용 가능한 노드만 추려 label을 붙인다. 이 개념을 익히면 어떤 데스크톱 자동화도 만들 수 있다.

퍼지 매칭으로 "이름→요소" 찾기

앱을 실행할 때 "노트패드"라고만 해도 정확한 실행 파일을 찾아야 한다. 이를 위해 thefuzz(레벤슈타인 거리 기반)로 가장 비슷한 항목을 고른다. 사람의 모호한 표현을 정확한 대상으로 매핑하는 실전 기법이다.

7하드웨어 / 시스템 요구사항

"이걸 돌리려면 뭐가 필요한가"에 대한 현실적 답.

무거운 모델을 로컬에서 돌리지 않으므로(LLM은 클라이언트/클라우드 몫) 요구사항은 가볍다. 단, 반드시 윈도우 본체에서 실행돼야 한다 — 윈도우 API를 직접 호출하기 때문이다(WSL에서 쓰려면 powershell.exe 브리지 필요).

8직접 해볼 수 있는 실습 과제

"읽기"에서 "하기"로 바꾸는 난이도별 과제.

9관련 기술 심화 학습 로드맵

이 레포를 발판으로 "에이전트 + 데스크톱 자동화"를 4주 코스로.

10핵심 키워드 사전

읽다 막히는 용어 빠른 참조.

11참고 링크

• GitHub: CursorTouch/Windows-MCP
• PyPI: windows-mcp (uvx windows-mcp serve)
• MCP 공식: Model Context Protocol · MCP Registry
• FastMCP: PrefectHQ/fastmcp
• UI Automation 라이브러리: Python-UIAutomation-for-Windows
• uv 패키지 매니저: Astral uv
• 관련 에이전트: Windows-Use (Windows-MCP 기반 에이전트)
• 커뮤니티: CursorTouch Discord