Cua Computer Server
Server component for the Computer-Use Interface (CUI) framework providing low-level computer control primitives.
Documentation - Installation, guides, and configuration.
Interfaces
The Computer Server exposes multiple interfaces simultaneously:
- HTTP/WebSocket - REST API and WebSocket for programmatic access
- MCP via HTTP - Model Context Protocol over streamable HTTP at
/mcpendpoint
Android emulators also expose the emulator's built-in EmulatorController gRPC service on port 8554 (via
-grpc 8554launch flag). Local Android sandboxes (AndroidEmulatorRuntime) useGRPCEmulatorTransportto callgetScreenshot()directly on this service, bypassing the computer-server HTTP layer entirely. Benchmark: p50 ~20ms, ~49 RPS vs ADB-backed HTTP p50 ~519ms, ~1.8 RPS.
Installation
# Basic installation (HTTP/WebSocket only)
pip install cua-computer-server
# With MCP support
pip install cua-computer-server[mcp]
# With the generated native Cua Driver SDK backend
pip install cua-computer-server[driver]
# With the VNC backend
pip install cua-computer-server[vnc]
Usage
# Start the server on default port 8000
python -m computer_server
# Or with custom port
python -m computer_server --port 8080
# Allow external access explicitly
python -m computer_server --host 0.0.0.0
# With resolution scaling (useful for Retina displays or VMs)
python -m computer_server --width 1512 --height 982
# Delegate portable whole-desktop actions to Cua Driver in this process
python -m computer_server --backend cua-driver --capture-scope desktop
# Or connect to an already-running Cua Driver daemon
python -m computer_server --backend cua-driver --driver-mode daemon
By default the server binds to 127.0.0.1. Deployments that need access from
other hosts should pass --host 0.0.0.0 or another explicit interface.
This provides:
- HTTP API at
/ws,/cmd,/statusendpoints - MCP server at
/mcpendpoint (requiresfastmcppackage)
MCP clients can connect via streamable HTTP at http://localhost:8000/mcp.
VNC backend
--backend vnc drives a remote target over RFB instead of the local OS, so it
covers screen, pointer, scroll, and keyboard only. Host-scoped surfaces (shell,
files, PTY, browser, windows) are refused rather than silently executed against
the server's own machine.
python -m computer_server --backend vnc \
--vnc-host 127.0.0.1 --vnc-port 5900 --vnc-password secret
The equivalent environment variables are CUA_VNC_HOST, CUA_VNC_PORT,
CUA_VNC_PASSWORD, and CUA_VNC_FORCE_CAPS.
Shift and non-compliant servers
RFB sends a keysym and leaves it to the server to work out which physical key
and modifiers produce it, so a compliant server presses Shift itself when it
receives underscore. QEMU only does that for uppercase letters: shifted
punctuation arrives unshifted, and Hello_World (a>b) is typed as
Hello-World 9a.b0.
Pass --vnc-force-caps (or set CUA_VNC_FORCE_CAPS=1) to send shift-<key>
from the client instead. It stays off by default: vncdotool documents it as a
workaround for non-compliant servers, and it changes what every uppercase and
shifted-punctuation keystroke puts on the wire.
When the server is started for you by the Python SDK, pass it through
Computer(...) instead — it is forwarded to the VM alongside the other VNC
settings:
computer = Computer(
backend="vnc",
vnc_host="127.0.0.1",
vnc_force_caps=True,
)
Cua Driver backend
--backend cua-driver keeps computer-server's HTTP/WebSocket, MCP, shell,
file, PTY, browser, accessibility, and window-management surfaces while routing
portable desktop capture, pointer, scroll, and keyboard actions through the
generated cua-driver Python SDK. The default embedded mode loads the Rust
runtime into computer-server and does not require a daemon. daemon mode is a
compatibility option for deployments that already own a long-lived driver.
The driver backend never falls back to OS-native input injection. Separate
mouse_down, mouse_up, key_down, and key_up calls return an explicit
unsupported-operation error; use drag, click, press_key, or hotkey
instead.
Each computer-server process opens a distinct driver session. Its capture scope
defaults to desktop, which enables the get_desktop_state command and
screen-absolute actions. Select auto or window with --capture-scope when a
stricter session policy is required. In auto, call escalate_capture_scope
with the concrete ladder-exhaustion reason before using desktop-only actions;
computer-server never escalates implicitly. Strict window sessions cannot
escalate. The equivalent environment variables are
CUA_DRIVER_MODE, CUA_DRIVER_SOCKET, CUA_DRIVER_SESSION_ID, and
CUA_DRIVER_CAPTURE_SCOPE.
Resolution Scaling
When running on Retina displays or in VMs where the coordinate system may differ, use the --width and --height flags to specify the target resolution:
- Screenshots will be resized to the target resolution
- Click coordinates received will be scaled from target to actual screen coordinates
- Cursor position will be reported in target coordinates
This ensures the AI model sees consistent coordinates between screenshots and mouse actions.
Claude Code Integration
- Start the server (or run as a service/LaunchAgent):
python -m computer_server --port 8000
- Add the MCP server URL to Claude Code:
claude mcp add cua-computer-server --transport http http://localhost:8000/mcp
Available MCP Tools
The MCP interface exposes 40+ tools for computer control:
Screen & Mouse
computer_screenshot- Capture current screencomputer_click- Click at coordinatescomputer_double_click- Double-clickcomputer_move- Move cursorcomputer_drag- Drag from start to end coordinatescomputer_scroll- Scroll at positioncomputer_get_screen_size- Get screen dimensionscomputer_get_cursor_position- Get cursor position
Keyboard
computer_type- Type textcomputer_press_key- Press a single keycomputer_hotkey- Press key combination (e.g., Ctrl+C)computer_key_down/computer_key_up- Hold/release keys
Clipboard
computer_clipboard_get- Get clipboard contentcomputer_clipboard_set- Set clipboard content
Shell
computer_run_command- Execute shell command
File System
computer_file_read/computer_file_write- Read/write filescomputer_file_exists/computer_directory_exists- Check existencecomputer_list_directory- List directory contentscomputer_create_directory- Create directorycomputer_delete_file/computer_delete_directory- Delete files/directories
Window Management
computer_open- Open file or URLcomputer_launch_app- Launch applicationcomputer_get_active_window- Get active windowcomputer_activate_window- Focus a windowcomputer_minimize_window/computer_maximize_window- Window statecomputer_close_window- Close window
Accessibility
computer_get_accessibility_tree- Get UI element treecomputer_find_element- Find UI element by role/title
Metadata
Release files for cua-computer-server 0.3.46
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cua_computer_server-0.3.46.tar.gz | 137.7 kB | Without provenance | Details for cua_computer_server-0.3.46.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cua_computer_server-0.3.46-py3-none-any.whl | Python 3 | none | any | Details for cua_computer_server-0.3.46-py3-none-any.whl |
Total release size: 271.5 kB
Release files / cua_computer_server-0.3.46.tar.gz
| Download URL | cua_computer_server-0.3.46.tar.gz |
|---|---|
| Size | 137.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3c434b421aa8f7dadcce5eeb92e186eae8f3c21e3720cc9da840a824e22e5494
|
|
BLAKE2b-256 checksum How to use checksums |
b4331b88061b137e19a8ed23bb4d027bf0e84cd5b95a6679a12c644a25b62a98
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / cua_computer_server-0.3.46-py3-none-any.whl
| Download URL | cua_computer_server-0.3.46-py3-none-any.whl |
|---|---|
| Size | 133.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
45f551d80054d8f993590b7428e94e7415501dbccdcda2ca5ad4148300883b3f
|
|
BLAKE2b-256 checksum How to use checksums |
7600ad010c3aa97010785aeb2c5ad3078b76009dd4c2ca691777102b09171eec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for cua-computer-server 0.3.46
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.