realtimex-pyautogui-server 0.2.0.dev1

RealTimeX MCP server for deterministic GUI control via PyAutoGUI

realtimex-pyautogui-server

RealTimeX's MCP server for deterministic desktop control with PyAutoGUI. This fork adapts the reference implementation with production defaults, a dedicated wait tool, and safeguards that prevent accidental keystrokes during pauses.

Features

• Mouse movement, clicks, and drag support with automatic coordinate scaling
• Keyboard typing and hotkeys
• Screen size, pixel, and screenshot utilities
• Dedicated wait(seconds) tool for precise pauses without injecting keystrokes
• Resolution-independent coordinates: Automatically scales coordinates from reference resolution to current screen
• Automatically releases modifier keys before typing to prevent stuck-shift issues
• Global PyAutoGUI defaults tuned for automation (PAUSE, FAILSAFE)

Coordinate Scaling

The server automatically scales mouse coordinates from a reference resolution (default: 1920×1080) to your current screen resolution. This allows you to use consistent coordinate values across different display configurations.

How It Works

• Define coordinates based on a reference screen (1920×1080 by default)
• move_mouse and drag_mouse automatically scale to your actual screen size
• Success messages show both original and scaled coordinates for debugging

Example

# On a 2560×1440 screen:
move_mouse(500, 90)  # Input: reference coordinates
# Output: "Mouse moved to coordinates (500, 90) [scaled to (666, 120)]."

Configuration

PyAutoGUI Settings

• Set REALTIMEX_FAILSAFE to 0 or 1 (default 1) to control PyAutoGUI's failsafe corner abort.
• Set REALTIMEX_PAUSE to a float (seconds) to override the global pause between PyAutoGUI actions (default 0.3).

Coordinate Scaling Settings

• Set REFERENCE_SCREEN_WIDTH to customize the reference screen width (default: 1920)
• Set REFERENCE_SCREEN_HEIGHT to customize the reference screen height (default: 1080)

Example:

export REFERENCE_SCREEN_WIDTH=2560
export REFERENCE_SCREEN_HEIGHT=1440
uvx realtimex-pyautogui-server

Usage

uvx realtimex-pyautogui-server

The server communicates over stdio and is compatible with MCP clients like Claude Desktop and the MCP Inspector.

Development

uv sync
uv run ruff check
uv run pytest