python-sdk

This MCP server exposes the Python CUP MCP endpoint for AI agents to query and control CUP-enabled desktop automation tasks. Once the server is running, agents can connect via MCP and use the provided tools to capture the current UI state, search semantically, and perform actions on applications and the desktop. Available tools include snapshot and snapshot_app to capture UI trees and app-specific views, overview to summarize the desktop state, snapshot_desktop for a full desktop envelope, find for element-based searches, action to execute interactions, open_app to launch applications, and screenshot for image-based captures. The server is designed to integrate with common MCP clients (e.g., Claude, Copilot) and conforms to the CUP MCP protocol so agents can request structured envelopes, perform actions, and receive results suitable for planning and reasoning in real time.

To use it, start the MCP server with the command above (python -m cup.mcp) and point your MCP client’s configuration at the server’s endpoint. The client can then request operations like retrieving a UI envelope, performing clicks or keystrokes, or opening apps, receiving results in the CUP envelope or action formats. The server handles platform-specific adapters and exposes a consistent, agent-friendly API surface for cross-platform automation.

Prerequisites:

• Python 3.8+ installed on your system
• Access to install Python packages (pip)
• On Linux, additional system packages may be required for UI access (e.g., python3-gi and gir1.2-atspi-2.0)

Installation steps:

1. Create and activate a Python virtual environment (optional but recommended): python -m venv venv source venv/bin/activate

2. Install the CUP Python package with MCP support: pip install computeruseprotocol[mcp]

3. (Optional) Install web and screenshot capabilities if you plan to use the web adapter or screenshot features: pip install computeruseprotocol[web] pip install computeruseprotocol[screenshot]

4. Run the MCP server: python -m cup.mcp

5. Verify the server is running by connecting a CUP MCP client or by checking logs for successful startup.

Tips and common notes:

• The MCP server auto-detects the host platform and loads the appropriate platform adapters (Windows, macOS, Linux, Web). If you encounter UI access issues on Linux, ensure the required GTK/AT-SPI dependencies are installed and that your environment has access to the display (e.g., running with a valid X server or Wayland session).
• If you plan to use the Web adapter or screenshot features, install the optional extras as shown in the installation steps.
• Tools exposed by the MCP server include: snapshot, snapshot_app, overview, snapshot_desktop, find, action, open_app, and screenshot. Each tool returns a CUP envelope or action result compatible with MCP client expectations.
• When running headless or in CI, some UI interactions may require a virtual display (e.g., Xvfb) or platform-specific workarounds for UI automation.
• Environment variables are typically not required for basic operation, but you can set configuration or logging preferences through your MCP client or by extending CUP’s config if needed.