프로젝트 소개

Windows-MCP는 AI 에이전트와 Windows 운영 체제를 연결하는 경량 오픈소스 MCP(Model Context Protocol) 서버입니다. Windows UI 자동화를 MCP 도구로 노출하여 에이전트가 파일 탐색, 애플리케이션 제어, UI 상호작용 및 QA 테스트를 수행할 수 있게 합니다. 주요 기능: - 네이티브 Windows 통합: 앱을 열고, 창을 제어하며, 키보드와 마우스 입력을 시뮬레이션하고, 창/UI 상태를 캡처합니다. - 모든 LLM과 호환되며, 기존의 컴퓨터 비전 파이프라인이나 미세 조정된 모델이 필요하지 않고 비전은 선택 사항입니다. - 기본 키보드/마우스 조작과 화면 또는 UI 스냅샷을 포함하는 UI 자동화 도구 세트. - 브라우저 자동화를 위한 DOM 모드: State 도구의 `use_dom=True` 옵션은 웹 페이지 콘텐츠에 집중하고 브라우저 크롬을 필터링합니다. Chrome, Edge, Firefox를 지원합니다(Firefox는 IAccessible2 폴백 사용). - 보고된 작업 간 일반적인 지연 시간은 약 0.2~0.5초이며, 시스템 부하와 LLM 추론 속도에 따라 달라집니다. 설치 및 실행: - Python 3.13+와 uv 패키지 관리자가 필요합니다. Windows 표시 언어로 영어를 권장하며, 그렇지 않으면 App 도구를 비활성화해야 합니다. - `uvx windows-mcp serve`로 직접 실행하거나, `windows-mcp install`로 사용자별 예약 작업으로 설치할 수 있습니다(`uninstall`로 제거). 로그는 `~/.windows-mcp/`에 저장됩니다. - stdio(기본), SSE, streamable-http 전송을 지원합니다. Claude Desktop, Perplexity Desktop, Gemini CLI, Qwen Code, Codex CLI, Autohand Code, Claude Code에 대한 설정 지침이 제공되며, powershell.exe를 통한 WSL 브리징도 포함됩니다. 보안 및 접근 제어: - Bearer 토큰 인증, CIDR 범위를 사용하는 IP 허용 목록, 선택적 CORS 오리진 허용 목록, 인증서 및 키 파일을 통한 TLS/HTTPS, 호환 클라이언트를 위한 PKCE 기반 OAuth 2.0. - `--tools` 허용 목록 또는 `--exclude-tools` 차단 목록을 통한 도구 선택. - 구성은 `~/.windows-mcp/config.toml`에 저장할 수 있으며, CLI 플래그가 파일 값을 덮어씁니다. `auth` 도우미가 키와 자체 서명 인증서를 생성할 수 있습니다. - Scrape 도구는 사설 IP, 루프백, 링크 로컬 주소, URL 내 자격 증명, 비HTTP 스킴을 차단합니다. 환경 변수는 스크린샷 스케일링 및 캡처 백엔드(dxcam/mss/pillow), 스냅샷 프로파일링, 캡처 플래시 비활성화, 보안 설정, 무상태 HTTP 모드, 익명 원격 측정(기본 활성화, 비활성화 가능), 디버그 로깅을 다룹니다. UIA 포커스 워치독을 사용할 수 있지만 기본적으로 꺼져 있습니다. 이 프로젝트는 MIT 라이선스이며 PyPI와 MCP Registry에 게시되어 있습니다.