mcp-winaccess

Cross-platform desktop automation via MCP adapter (adapter/windows.py, adapter/linux.py, adapter/macos.py).

Usage Example

Related MCP server: Clara Windows UI MCP

Install

pip install mcp-winaccess
uv tool install mcp-winaccess

Run

uvx mcp-winaccess

Or directly:

python server.py

OpenCode Config (opencode.jsonc)

{
  "mcp": {
    "winaccess": {
      "type": "local",
      "command": [
        "uvx",
        "mcp-winaccess"
      ],
      "enabled": true
    }
  }
}

Tools

Always Available

• screenshot_base64(): Captures full desktop screen and returns base64-encoded JPEG (IMAGE_BASE64:...). No parameters. Call when agent needs visual screen feedback.

• screenshot_jpg(path: str): Captures full desktop screen and saves .jpg to the given file path (path). Returns confirmation with saved path. Call when agent needs to persist screenshot to disk.

• click(x, y): Left-click at absolute screen coordinates (x, y pixels).

• double_click(x=0, y=0): Double-click at absolute screen coordinates. If both x and y are 0, uses current mouse position.

• double_click_element(value, control_identifier="", x=0, y=0): Double-click a control inside a window (value = partial title str or handle int; control_identifier = index-based ID element_N or AutoID/Name). If value and control_identifier are provided, performs element-based double click at control center; otherwise uses coordinate mode.

• right_click(x=0, y=0): Right-click at absolute screen coordinates. Defaults to current position when x=y=0.

• drag(x_from, y_from, x_to, y_to, duration=0.5): Drag mouse from start (x_from, y_from) to end (x_to, y_to) over duration seconds.

• drag_element(value, control_identifier, x_to, y_to, duration=0.5): Drag a UI control (control_identifier from get_all_controls) inside window (value) to target screen coordinates (x_to, y_to).

• move_mouse(x, y): Move cursor to absolute coordinates (x, y) without clicking.

• scroll(direction="down", amount=3, x=0, y=0): Scroll mouse wheel down or up at coordinates (x, y) for amount steps.

• type_text(text): Type text at current keyboard focus.

• run_app(exe_path): Launch executable at exe_path.

• kill_app(name): Kill process by executable base name (name, without .exe) using taskkill /F /IM.

• switch_to_window(value): Restore and activate window by partial title (str) or handle (int).

Window Automation (Windows / Linux with pywinauto / pyatspi)

• find_window(value?): Find visible top-level window by partial title (str) or handle (int). Returns info with title, class, handle, pid, rect.

• list_windows(): List visible windows.

• click_element(value, control_identifier): Click UI control inside window. value = partial title (str) or handle (int); control_identifier = index-based ID (element_0) or AutoID/Name.

• read_text(value, control_identifier): Read control text by ID.

• manage_window(value, action="maximize", x=0, y=0): Manage window state (minimize/maximize/restore/move). value = title (str) or handle (int).

• wait_for_window(value, timeout?): Wait for window by partial title (str) or handle (int).

• get_all_controls(value): List child controls inside window (value = title str or handle int). Returns index-based IDs (element_0, element_5), AutoID, Name, Class, Type, Text, Handle. Agents must use the ID value (e.g., element_5) as control_identifier for interaction with controls.

• wait_for_element(value, control_identifier, timeout?): Wait for control by ID.

• get_window_state(value): Window state info (str or int).

• get_text(value, control_identifier): Full text from control.

• set_text(value, control_identifier, value_text): Set text in edit control.

• type_in_element(value, control_identifier, text): Type directly into control.

Unsupported functions are hidden from MCP on each platform.