왜 FlaUI-MCP 인가?
Claude Code, Copilot, Codex 등 코딩 에이전트들이 브라우저를 자동화 할 때는 Playwright MCP 라는 잘 정립된 표준이 존재함.
하지만 Windows 데스크톱 앱을 자동화하려고 하면 상황이 달라짐. 기존 접근 방식들은 대부분 이하의 한계를 가지고 있음.
•
스크린샷 + Vision 방식: 느리고, 비용이 크며, 해상도에 의존적이고 부정확함
•
좌표 기반 클릭: 화면 구성이 바뀌거나 DPI 가 달라지면 즉시 깨짐
•
앱마다 매번 별도의 자동화 스크립트를 작성해야 함
이러한 문제를 해결하기 위해 FlaUI-MCP 를 개발
Playwright 가 브라우저를 자동화하는 방식 그대로, Windows 데스크톱 앱을 동일한 패턴으로 자동화할 수 있도록 만든 MCP 서버임.
Playwright (브라우저) | FlaUI-MCP (Windows 앱) |
browser_snapshot | windows_snapshot |
browser_click ref="..." | windows_click ref="w1e5" |
왜 Upstream 을 하드 포크 했는가?
원본 저장소는 컨셉 자체는 훌륭했으나, 실사용 단계에 들어가면서 몇 가지 명확한 문제들이 보이기 시작함.
•
유지보수 정체: 이슈와 PR 이 누적되어도 반영되지 않음. upstream 으로의 기여(contribution)를 통한 개선은 현실적으로 어려움
•
실사용 환경에서 드러나는 안정성 이슈: UWP 앱 / 다국어 윈도우 타이틀에서의 핸들 매칭 실패, 장시간 세션에서의 핸들·GDI 누수, 비동기 UI 변화에 대한 대응 부재 등
•
표준 미준수: JSON-RPC 2.0 및 MCP 사양 준수가 일관적이지 않아 일부 클라이언트와의 호환성 문제 발생
•
요구되는 신규 기능: 트레이 아이콘 자동화, 컨텍스트 메뉴 핸들링, Win32 다이얼로그 처리, 스크린샷 diff 기반 검증 등 실무에서 빈번하게 필요한 기능들이 부재
•
배포 인프라 부재: 멀티 아키텍처(win-x64 / win-arm64) 빌드와 자동화된 릴리즈 파이프라인이 없음
단순한 패치 수준으로는 해결이 어렵고, upstream 의 반영 일정을 기다리는 것 또한 비현실적이라고 판단됨.
이에 따라 유지보수 책임을 명시적으로 분리하고 독립적인 로드맵으로 발전시키기 위해, 단순 fork 가 아닌 하드 포크 형태로 분리
upstream 에 대한 존중은 유지하되, 안정성 / 표준 / 기능 / 배포 네 축을 중심으로 재정비하는 것이 본 포크의 목적임.
핵심 컨셉: 스크린샷이 아닌 접근성 트리
FlaUI-MCP 는 Windows UI Automation API 를 통해 화면 요소들의 접근성 트리(Accessibility Tree)를 가져옴.
이는 스크린 리더가 사용하는 것과 동일한 API 이며, 프로그램적인 UI 상호작용을 위해 설계된 공식 인터페이스임. 즉, 화면 픽셀을 추측하는 것이 아니라 운영체제가 알려주는 의미 기반(Semantic) 정보를 그대로 활용하게 됨.
windows_snapshot 호출 시 반환되는 트리 구조의 예시:
- window "Calculator" [ref=w1e1]
- group "Number pad" [ref=w1e39]
- button "Seven" [ref=w1e47]
- button "Eight" [ref=w1e48]
- button "Nine" [ref=w1e49]
- text "Display is 0" [ref=w1e15]
Plain Text
복사
각 요소는 이하의 정보를 보유
•
Role: button, text, group 등의 역할
•
Name: "Seven", "Display is 0" 등 사람이 읽을 수 있는 이름
•
Ref: w1e47 처럼 상호작용에 사용되는 핸들
•
State: [disabled], [readonly], [checked] 등 상태
두 가지 접근 방식의 비교:
접근 방식 | 장점 | 단점 |
Accessibility Tree | 의미 기반, 정확, 빠름, 해상도 독립적 | UI Automation 지원 필요 |
Screenshot + Vision | 어떤 앱이든 동작 | 느리고 비싸며 부정확, 해상도 의존 |
지원되는 앱 범위:
•
Win32 (메모장, 탐색기 등)•
WPF / WinForms•
UWP / Store 앱 (계산기, 설정 등)•
Electron 앱 (앱의 접근성 구현 정도에 따라 부분 지원)•
게임 (UI Automation 미지원이 일반적)주요 도구
총 32 개의 windows_* 도구를 제공하며, 카테고리별로 분류하면 이하와 같음.
카테고리 | 대표 도구 |
Session | windows_launch, windows_attach |
Window | windows_list_windows, windows_focus, windows_close, windows_window_state |
Inspect | windows_snapshot, windows_inspect, windows_screenshot, windows_screenshot_diff |
Values | windows_get_value, windows_set_value |
Clipboard | windows_get_clipboard, windows_set_clipboard |
Mouse | windows_click, windows_hover, windows_scroll, windows_drag |
Keyboard | windows_type, windows_fill, windows_keys |
Tray & Menu | windows_tray_list, windows_tray_invoke, windows_context_menu, windows_dialog |
Flow | windows_batch, windows_wait_for, windows_assert |
특히 Discord, Slack 처럼 트레이로 최소화되는 앱을 다루기 위한 windows_tray_list / windows_tray_invoke, 컨텍스트 메뉴를 핸들로 등록해 사라지지 않게 추적하는 windows_context_menu, 일반 Win32 다이얼로그(파일 열기/저장 등)를 한 번에 처리하는 windows_dialog 가 강점임.
설치 방법
사전 요구 사항
•
Windows 10 / 11
•
.NET 8.0 Runtime (릴리즈 바이너리용) 또는 .NET 8.0 SDK (플러그인 / 소스 빌드용)
Claude Code 플러그인으로 설치
Claude Code 사용자라면 두 줄의 명령어만으로 설치가 끝남. MCP 설정 파일을 직접 수정할 필요가 없음.
/plugin marketplace add starpia-forge/FlaUI-MCP
/plugin install flaui-mcp@flaui-mcp-marketplace
Shell
복사
설치 후 Claude Code 가 MCP 서버를 자동으로 spawn 하며, 즉시 32 개의 windows_* 도구를 세션에서 사용 가능
최초 실행 시 약 10 ~ 30 초 정도 빌드 시간이 소요됨. 이후 실행부터는 캐시된 빌드를 재사용하여 1 ~ 3 초 내에 기동.
업데이트 / 제거:
/plugin update flaui-mcp@flaui-mcp-marketplace
/plugin uninstall flaui-mcp@flaui-mcp-marketplace
Shell
복사
릴리즈 바이너리로 설치
Releases 페이지 에서 릴리즈 별로 4 종의 아티팩트가 제공됨.
Artifact | 선택 기준 |
win-x64-<v>-self-contained.zip | x64 Windows, .NET 미설치 환경 |
win-x64-<v>-framework-dependent.zip | x64 Windows, .NET 8 런타임 설치된 환경 |
win-arm64-<v>-self-contained.zip | ARM64 Windows (Surface Pro X, Copilot+ PC 등), .NET 미설치 |
win-arm64-<v>-framework-dependent.zip | ARM64 Windows, .NET 8 런타임 설치된 환경 |
ZIP 을 임의 폴더에 풀면 FlaUI.Mcp.exe 실행 파일이 생성됨.
MCP 클라이언트 설정
~/.copilot/mcp-config.json 등 사용 중인 MCP 클라이언트 설정 파일에 이하를 추가
{
"mcpServers": {
"windows": {
"type": "local",
"command": "C:\\\\path\\\\to\\\\FlaUI-MCP.exe",
"tools": ["*"]
}
}
}
JSON
복사
사용 예시
에이전트가 계산기에서 3 × 3 을 계산하는 흐름:
Agent: Calculate 3 × 3
1. windows_launch { "app": "calc.exe" }
→ Window handle: w1
2. windows_snapshot { "handle": "w1" }
→ - window "Calculator" [ref=w1]
- button "Three" [ref=w1e43]
- button "Multiply by" [ref=w1e35]
- button "Equals" [ref=w1e38]
- text "Display is 0" [ref=w1e15]
3. windows_batch { "actions": [
{"action": "click", "ref": "w1e43"},
{"action": "click", "ref": "w1e35"},
{"action": "click", "ref": "w1e43"},
{"action": "click", "ref": "w1e38"},
{"action": "snapshot", "handle": "w1"}
]}
→ ... "Display is 9" ...
Plain Text
복사
좌표나 이미지 인식 없이 요소 ref 하나로 모든 상호작용이 이루어지는 것이 핵심.
windows_batch 를 통해 여러 액션을 단일 호출로 묶으면 LLM 의 round-trip 비용도 크게 줄일 수 있음.
Upstream 과의 차이점
하드 포크 시점 기준으로, upstream 인 shanselman/FlaUI-MCP 대비 이하의 항목들이 개선 / 추가됨.
안정성
•
HWND 기반 윈도우 감지로 UWP 앱과 다국어 윈도우 타이틀에서도 안정적으로 동작
•
비동기 UI 변화에 대한 auto-wait / retry executor 도입
•
장시간 세션에서 발생하던 핸들 / GDI 누수 해소
표준 준수
•
JSON-RPC 2.0 / MCP 사양 준수로 다양한 MCP 클라이언트와의 호환성 확보
기능 확장
•
트레이 아이콘 자동화 (windows_tray_list, windows_tray_invoke)
•
컨텍스트 메뉴 핸들 등록 / 해제 (windows_context_menu, windows_dismiss_menu)
•
Win32 공용 다이얼로그 처리 (windows_dialog)
•
스크린샷 diff 기반 시각적 변화 검증 (windows_screenshot_diff)
•
포커스 추적 (windows_focused_element), Grid 셀 접근 (windows_grid_cell) 등
배포 / 품질
•
semantic-release 기반 자동 릴리즈 파이프라인 구축
•
win-x64 + win-arm64 멀티 아키텍처 빌드 및 배포
•
xUnit 테스트 스위트 (ElementRegistry, SnapshotBuilder, ConditionEvaluator, KeyMap)
•
Claude Code 플러그인 마켓플레이스 지원
