Astrax – Open-source MCP server for Windows desktop AI control

Open-source developer AstraxOf released Astrax, an open-source Model Context Protocol server written in Python that provides artificial intelligence models with direct desktop automation capabilities across Windows, macOS, and Linux, according to github.com's report. Short for Agentic System Telemetry, Realtime Automation and X-control, the system connects local and commercial language models to mouse, keyboard, screen vision, clipboard, and shell execution interfaces using the standard input and output transport. The release focuses on executing multi-step desktop operations without exhausting context windows through an isolated local task engine, while providing single-command setup routines that register the server directly into tools like Claude Desktop, Roo Code, Cline, Cursor, Windsurf, Gemini CLI, and OpenCode.

This technical report details the architecture, configuration parameters, state management mechanisms, and safety boundaries introduced in the Astrax project. It serves system architects, developers configuring local agentic workflows with Ollama, and power users deploying commercial agents through Claude or Gemini who require desktop automation without token bloat. The analysis explains how Astrax manages persistent step execution via local JSON state, how permission gating limits agent access before automation starts, and what structural limits engineers must consider when running desktop control servers over standard operating system environments.

Astrax – Open-source MCP server for Windows: what actually changed

Astrax introduces a dedicated Model Context Protocol server that translates structured model tool calls into concrete desktop actions while bypassing manual configuration file editing. Instead of requiring users to construct client configurations by hand, the project provides an automated installer executed via Astral's uv package manager using the command uvx with the remote Git repository target. The installer inspects the local operating system, discovers installed MCP clients, creates atomic backups named with timestamp suffixes, and injects only the astrax entry into client configuration files while preserving all existing server definitions and rejecting invalid JSON files.

The setup utility provides flags including list to audit installed clients, client to target specific applications such as Claude Desktop or Cursor, and auto-approve to preconfigure permissions for Roo Code and Cline. A local fallback mode allows direct execution using an existing Python runtime, while the uninstaller removes only the specific astrax server key. For manual configurations, Astrax can be registered directly in mcp_settings.json by running uvx against the remote Git repository. These configuration mechanisms establish a standardized channel for sending coordinates, keystrokes, and terminal instructions from disparate model providers directly into operating system windowing APIs.

Astrax – Open-source MCP server for Windows: how it works

The core architecture operates around an isolated state engine designed to prevent language model degradation during long-running tasks. Light open-source models running locally on Ollama frequently suffer from hallucination and performance loss when old screenshots and repetitive execution logs accumulate inside the conversation context. Astrax addresses this by storing workflow progress in an isolated local JSON file named .astrax_task_state.json located inside restricted cache directories such as AppData Local on Windows, or user cache folders on macOS and Linux, customizable through the ASTRAX_HOME environment variable.

When a user submits a multi-step prompt, the model calls astrax_tarea_crear to register an ordered plan. As execution advances, the model calls astrax_tarea_estado to read only the current step, the immediate next step, and necessary cached variables, receiving a lightweight payload rather than the entire conversational history. Steps store exact references such as file paths capped at 4,000 characters rather than raw document contents. Visual feedback occurs selectively through astrax_ver_pantalla, which returns image data marked with a red cursor indicator, while regular mouse clicks, scrolling, shell execution, and non-ASCII typing via clipboard injection emit compact textual confirmations.

Astrax – Open-source MCP server for Windows: why it matters now

Language models operating desktop environments often encounter severe context window saturation because full-screen imagery and lengthy terminal buffers consume token budgets rapidly. By isolating intermediate outputs into local JSON files and serving only immediate step instructions, Astrax allows small open-source models to complete complex workflows that previously required massive cloud context windows. An automatic anti-loop safeguard tracks step failures, marking any operation that fails three consecutive times as blocked and halting execution so the model can report the roadblock to the user rather than looping indefinitely.

Security in autonomous desktop control represents another critical operational challenge. Astrax enforces a single-authorization model where the artificial intelligence must declare all necessary permissions across screen, mouse and keyboard, clipboard, and terminal interfaces before starting. Once the user approves the declared scope, the server grants access for a default session duration of 60 minutes, configured via ASTRAX_SESSION_MINUTES. Individual tool endpoints reject calls attempted outside an authorized session, while built-in validation checks screen coordinate boundaries, provides a manual mouse-corner fail-safe to abort automation immediately, and blocks destructive shell commands including rm -rf, mkfs, format, and shutdown.

Astrax – Open-source MCP server for Windows: who is affected

Software engineers, accessibility developers, and technical teams operating multi-model agent environments can deploy Astrax across heterogeneous toolchains. The server supports proprietary models via Claude Desktop, Windsurf, Cursor, and Gemini CLI alongside local inference platforms running Ollama, allowing developers to switch between local privacy-focused agents and commercial APIs without changing desktop automation tool interfaces. Terminal agent implementations such as Claude Code can register the server using standard command-line flags pointing directly to the uvx runner.

Platform support varies across operating systems. Windows installations operate immediately without auxiliary display configurations. macOS installations require explicit operating system authorization for Screen Recording and Accessibility granted to the calling terminal or editor application. Linux environments require an active X11 display server, as standard Wayland protocols generally block screen capture and synthetic input control; Linux setups may also require system packages including python3-tk, python3-dev, scrot, and xclip to support display capture and clipboard synchronization.

Astrax – Open-source MCP server for Windows: what to watch

The implementation codebase divides responsibilities across specialized Python modules inside src/astrax_mcp, separating server configuration, task state processing, vision capture, system commands, and lazy GUI interactions. Developers monitoring the project should watch for the planned official release on PyPI, which will simplify invocations from Git repository targets down to standard package executions via uvx astrax-mcp. Users can also configure ASTRAX_REQUIRE_SESSION to zero if they need to disable session boundaries and revert to unmanaged tool calling.

Operational safety remains a key focus as deployment expands across consumer workstations. The project maintainers maintain an instructional tutorial channel on YouTube under @AstraxOf and direct developer support on Telegram via @RufusOficial. Because the server interacts directly with hardware inputs and shell execution rather than running inside an isolated sandbox, administrators must maintain active supervision when granting terminal permissions and avoid running automated tasks while sensitive personal data, administrative interfaces, or banking sessions remain open in active application windows.