Astrax가 AI의 윈도우 화면 조작을 지원한다

Astrax는 파이썬으로 만든 오픈소스 MCP(Model Context Protocol) 서버다. AI가 화면을 보고 마우스와 키보드를 조작하며 여러 단계의 작업을 수행하도록 돕는다. 제작자는 대화 기록과 오래된 화면 캡처가 쌓여 모델의 컨텍스트가 커지는 문제를 줄이기 위해 작업 상태를 로컬 파일에 저장한다고 설명한다.

Claude Desktop, Roo Code, Cline, Cursor, Windsurf, Gemini CLI, OpenCode 등 stdio 전송을 지원하는 MCP 클라이언트와 호환된다. Ollama 같은 로컬 모델과 Claude, Gemini 등 상용 API를 사용하는 모델도 지원한다. Astrax 저장소

설치와 설정

설치에는 파이썬과 의존성을 설치하는 uv가 필요하다. 원문은 다음 명령으로 uv를 설치하도록 안내한다.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

그다음 설치 명령 하나로 운영체제와 MCP 클라이언트를 감지하고 Astrax를 등록한다.

uvx --from git+https://github.com/AstraxOf/astrax-mcp.git astrax-install --yes

설치가 끝나면 클라이언트를 다시 시작해야 한다. Claude Desktop은 완전히 종료한 뒤 다시 열어야 한다. Astrax 패키지가 PyPI에 게시되면 서버 실행에는 uvx astrax-mcp를, 설치에는 uvx --from astrax-mcp astrax-install --yes를 사용할 수 있다고 저장소는 안내한다.

터미널에 접근할 수 있는 AI 에이전트가 Astrax 설치를 요청받았을 때 실행하도록 저장소가 제시한 명령은 다음과 같다. 실행 후 MCP 클라이언트를 다시 시작하도록 요청해야 하며, JSON 파일을 직접 편집하지 말라고 안내한다.

uvx --from git+https://github.com/AstraxOf/astrax-mcp.git astrax-install --yes

설치 프로그램은 다음 옵션을 제공한다.

• astrax-install --list: 감지한 클라이언트와 Astrax 설치 여부를 표시한다.
• astrax-install --client claude-desktop: 지정한 클라이언트 하나에만 설치한다. 반복해서 실행할 수 있다. 클라이언트 ID는 claude-desktop, roo-code, cline, cursor, windsurf, gemini-cli다.
• astrax-install --auto-approve: Roo Code와 Cline에서 astrax_tarea_autorizar를 제외한 모든 도구에 alwaysAllow를 추가한다. 권한 동작은 아래의 권한 설명을 참고한다.
• astrax-install --dry-run: 파일을 쓰지 않고 실행할 작업을 표시한다.
• astrax-install --uninstall: astrax 항목만 제거한다.
• astrax-install --source local: uvx 대신 현재 파이썬을 사용한다.

설치 프로그램은 mcpServers 안의 astrax 키만 수정한다. 다른 서버 설정은 보존하고, 파일을 쓰기 전에 .astrax-bak-<fecha> 형식의 사본을 만들며, 원자적으로 저장한다. JSON이 유효하지 않은 파일은 수정하지 않는다.

Claude Code에서는 다음 명령으로 서버를 추가할 수 있다.

claude mcp add astrax -- uvx --from git+https://github.com/AstraxOf/astrax-mcp.git astrax-mcp

저장소를 복제해 설치하려면 다음 명령을 사용한다.

git clone https://github.com/AstraxOf/astrax-mcp.git
cd astrax-mcp
python install.py # asistente interactivo (equivale a astrax-install)

설치 프로그램을 쓰지 않으려면 클라이언트의 mcp_settings.json이나 이에 해당하는 파일에 다음 설정을 추가한다.

{
 "mcpServers": {
 "astrax": {
 "command": "uvx",
 "args": ["--from", "git+https://github.com/AstraxOf/astrax-mcp.git", "astrax-mcp"]
 }
 }
}

사용 중인 데스크톱 클라이언트가 PATH를 상속하지 않는다면 uvx의 절대 경로를 지정해야 한다. 원문은 which uvx 또는 where uvx로 경로를 확인할 수 있으며, 설치 프로그램은 이를 대신 처리한다고 설명한다.

작업 상태와 권한

Astrax는 작업 계획과 진행 상태를 .astrax_task_state.json에 저장한다. 저장소는 대화 기록과 오래된 화면 캡처가 컨텍스트를 키워 Ollama 같은 경량 모델이 포화되거나 환각을 일으키는 상황을 이 방식으로 피한다고 설명한다.

복잡한 요청을 받으면 AI는 astrax_tarea_crear를 호출해 작업 계획을 순서가 있는 단계로 저장한다. 각 단계에서는 astrax_tarea_estado를 호출해 전체 대화나 초기 프롬프트, 과거 캡처를 다시 읽는 대신 현재 단계와 다음 단계, 저장된 데이터만 받는다. 이 데이터는 몇 줄 정도의 JSON이다.

단계를 마칠 때 AI는 astrax_tarea_completar_paso로 필요한 결과를 저장할 수 있다. 예를 들어 생성한 PDF의 경로를 {"pdf_generado": "/rutas/carta.pdf"}처럼 기록하면, 다음 단계에서 이메일에 첨부할 때 경로를 추측하지 않고 저장된 값을 사용할 수 있다. 마지막 단계가 끝나면 작업은 completada 상태가 되고 권한이 회수되며 임시 캡처가 삭제된다. astrax_tarea_limpiar는 상태 파일을 삭제한다.

상태 관리에는 다음 제한과 보호 기능이 있다.

• 콘텐츠 자체보다 경로를 저장한다. 데이터 한 항목은 최대 4000자까지 허용하며, 이를 넘으면 도구가 파일에 저장하고 경로를 기록하도록 요청한다.
• 한 단계가 세 번 실패하면 bloqueada 상태가 된다. 이 경우 AI는 멈추고 사용자에게 발생한 일을 설명해야 한다.
• 동작 도구는 짧은 텍스트를 반환한다. 확인이 필요한 경우에만 astrax_ver_pantalla가 이미지를 반환해 과거 캡처가 대화 기록에 쌓이지 않도록 한다.
• 상태 파일은 사용자 전용 폴더에 저장되며 접근 권한이 제한된다. 경로는 ~/.cache/astrax, ~/Library/Caches/astrax 또는 %LOCALAPPDATA%\\astrax다. ASTRAX_HOME으로 위치를 바꿀 수 있다.

작업을 시작하기 전에 AI는 astrax_tarea_crear에서 해당 작업 전체에 필요한 권한을 선언한다. 권한 종류와 허용되는 기능은 다음과 같다.

• pantalla: astrax_ver_pantalla, astrax_capturar_pantalla를 사용할 수 있다.
• raton_teclado: 클릭과 더블 클릭, 키 입력, 단축키, 스크롤, 텍스트 입력을 할 수 있다.
• portapapeles: astrax_portapapeles를 사용할 수 있고, ñ와 악센트 문자, 이모지 등 ASCII가 아닌 텍스트를 입력할 수 있다.
• terminal: astrax_ejecutar_comando를 사용할 수 있다.

AI는 계획과 권한을 먼저 보여주고 사용자에게 한 번 확인을 받은 뒤 astrax_tarea_autorizar를 호출한다. 그 뒤에는 세션 동안 사용자 개입 없이 작업할 수 있다. 기본 세션 길이는 60분이며 ASTRAX_SESSION_MINUTES로 바꿀 수 있다. 승인된 작업에 포함되지 않거나 요청하지 않은 권한을 사용하는 동작 도구는 요청을 거부한다.

클라이언트가 단계마다 확인을 요구하는 동작은 서버가 건너뛸 수 없다. Roo Code와 Cline에서는 astrax-install --auto-approve를 사용하면 astrax_tarea_autorizar를 제외한 모든 도구를 항상 허용하도록 설정할 수 있다. 이 경우 클라이언트는 작업 실행 중이 아니라 권한 승인 시점에 한 번 묻는다. Claude Desktop 등 다른 클라이언트에서는 해당 도구나 나머지 도구에 대한 확인을 요청받을 때 ‘항상 허용’을 선택할 수 있다. 작업과 세션을 사용하지 않는 이전 동작으로 돌아가려면 ASTRAX_REQUIRE_SESSION=0으로 설정한다.

화면 제어 도구와 안전 주의사항

Astrax가 제공하는 도구는 작업 관리, 화면 확인, 입력 제어, 시스템 기능으로 나뉜다.

• 작업 관리: astrax_tarea_crear는 단계별 계획과 필요한 권한을 저장한다. astrax_tarea_autorizar는 사용자 확인 뒤 권한을 부여한다. astrax_tarea_estado는 현재 단계와 다음 단계, 저장된 데이터를 읽는다. astrax_tarea_guardar는 경로나 ID 같은 핵심 데이터를 저장한다. astrax_tarea_completar_paso는 단계를 끝내고 결과를 저장해 다음 단계를 반환한다. astrax_tarea_limpiar는 상태와 임시 캡처를 지운다.
• 화면과 입력: astrax_ver_pantalla는 커서 위치에 빨간 표시를 넣은 화면 이미지를 반환한다. astrax_capturar_pantalla는 PNG를 저장하고 경로를 반환한다. astrax_info_pantalla는 화면의 너비와 높이를 알려준다. astrax_clic과 astrax_doble_clic은 화면 좌표 (x, y)를 확인한 뒤 클릭한다. astrax_escribir는 텍스트를 입력하며, ñ와 악센트 문자, 이모지는 클립보드를 통해 입력한다. astrax_tecla와 astrax_atajo는 개별 키와 ["ctrl", "t"] 형식의 단축키를 처리한다. astrax_scroll은 마우스 휠을 위아래로 움직이고, astrax_esperar는 앱이나 페이지가 로드될 때까지 기다린다.
• 시스템 기능: astrax_portapapeles는 클립보드 내용을 읽거나 쓴다. astrax_ejecutar_comando는 제한 시간과 출력 길이 제한을 적용해 셸 명령을 실행한다.

저장소는 다음과 같은 요청을 사용 예로 제시한다.

“Astrax를 사용해 내 정보로 아나에게 보낼 편지를 작성하고 PDF로 저장한 뒤, 제목을 ‘제안’으로 해서 ana@ejemplo.com에 보내.”

Astrax는 실제 마우스와 키보드를 제어하며, 사용자가 허용하면 터미널도 조작한다. 저장소는 사용에 주의를 기울이라고 안내하며 다음 보호 기능과 주의점을 명시한다.

• 안전 중단 기능이 활성화돼 있다. 마우스를 화면 모서리로 옮기면 자동화를 중단한다.
• AI는 요청하고 사용자가 확인한 최소 권한만 받는다. 작업이 끝나거나 차단되면 권한은 회수된다.
• 화면 경계를 벗어나는 클릭은 거부된다.
• astrax_ejecutar_comando는 rm -rf /, mkfs, format C:, shutdown 등 명백히 파괴적인 패턴을 차단한다. 저장소는 이를 사고 방지를 위한 안전장치이지 샌드박스는 아니라고 설명한다. 작업을 신뢰하고 감독할 수 있을 때만 terminal 권한을 허용해야 한다.
• 비밀번호나 은행 정보 등 민감한 데이터가 열린 상태에서는 실행하지 말라고 안내한다.

운영체제별로 필요한 설정도 다르다. Windows에서는 별도 설정 없이 작동한다. macOS에서는 터미널이나 편집기에 화면 기록과 손쉬운 사용 권한을 부여해야 한다. Linux에서는 X11에서 작동하지만 Wayland는 화면 캡처와 제어를 막는 경우가 많다. Linux에서는 sudo apt install python3-tk python3-dev scrot xclip이 필요할 수 있다.

구현 정보

저장소는 공식 파이썬 MCP SDK를 기반으로 한다. compat.py는 MCP SDK v2의 MCPServer를 사용하고, v1.x에서는 FastMCP로 대체한다. pyproject.toml에는 원래 설정대로 mcp<2 제한이 들어 있다. SDK v2를 시험할 때는 이 제한을 제거하라고 안내한다.

전송 방식은 stdio이며 JSON-RPC 흐름이 깨지지 않도록 로그는 모두 stderr로 보낸다. 화면 캡처는 논리적 화면 크기에 맞게 정규화하므로 HiDPI와 Retina 화면에서도 이미지 좌표가 클릭 좌표와 일치한다. JPEG 품질은 기본값 65이며 ASTRAX_JPEG_QUALITY로 30~95 범위에서 조절할 수 있다.

저장소의 디렉터리 구성은 다음과 같다.

astrax-mcp/ ├── pyproject.toml          # entry points: astrax-mcp, astrax-install ├── install.py              # atajo para quien clona el repo ├── mcp_settings.json       # ejemplo (Roo Code / Cline) ├── tests/ └── src/astrax_mcp/     ├── server.py           # construye el servidor y registra los módulos     ├── config.py           # constantes, rutas y variables ASTRAX_*     ├── state.py            # motor del archivo de estado de tareas (sin dependencias de MCP)     ├── tasks.py            # herramientas MCP del gestor de tareas     ├── permissions.py      # verificación de permisos de sesión     ├── vision.py           # captura y visión de pantalla     ├── control.py          # ratón, teclado, scroll, esperas     ├── system.py           # terminal y portapapeles     ├── gui.py              # acceso perezoso a pyautogui + validaciones     ├── utils.py            # log a stderr, errores uniformes, truncado     ├── compat.py           # SDK MCP v1 (FastMCP) / v2 (MCPServer)     └── installer.py        # wizard de instalación multiplataforma `

테스트는 다음 명령으로 실행하도록 저장소에 기재돼 있다.

pip install -e ".[dev]" && pytest

Astrax는 오픈소스 프로젝트로, 저장소는 이슈와 풀 리퀘스트 제출, 아이디어 제안, 다른 운영체제나 MCP 클라이언트에서의 시험과 오류 보고를 기여 방식으로 안내한다.