typescript-sdk

The CUP MCP server exposes the Computer Use Protocol tooling to AI agents, allowing them to discover UI trees, execute actions, and perform semantic searches against a host machine's UI. The server integrates with the SDK’s session and action APIs, and provides tools such as snapshot, snapshot_app, overview, snapshot_desktop, find, action, open_app, and screenshot to enable conversational automation and scripted interactions. To use it, run the MCP server and point your MCP client to the provided server alias (e.g., cup). The client can then request tree captures, search for elements by query, execute clicks and key presses, or open applications, enabling agents like Claude or Copilot to interact with desktop UI in a controlled, protocol-compliant manner.

Prerequisites:

• Node.js (version 14+ recommended) and npm or bun
• Basic familiarity with MCP clients and JSON configuration

Installation steps:

1. Install the MCP server package globally using npm/npx or bun:

   • npm: npm install -g cup-mcp
   • or using npx directly: npx cup-mcp
   • bun: bun install -g cup-mcp (if using Bun)

2. Confirm installation:

   • npx cup-mcp --version

3. Run the MCP server (example):

   • npx cup-mcp

4. Optional: create an MCP client config file (.mcp.json) with the server reference: { "mcpServers": { "cup": { "command": "npx", "args": ["cup-mcp"] } } }

Notes:

• The server exposes tools like snapshot, overview, find, action, and more for automation.
• If your environment requires a specific path to the server binary, you can adjust the command/args accordingly in your config.

Tips and notes:

• Ensure you have the necessary platform adapters installed and that the host OS matches the CUP server requirements (Windows, macOS, Linux; Web/Chrome CDP is supported).
• Some UI automation may require accessibility permissions (macOS) or elevated privileges (Windows) to capture trees and perform actions.
• When using semantic search (find), provide clear queries to improve accuracy (e.g., {"query": "submit button"}).
• If the MCP client cannot connect, verify network accessibility and that the server is running with the expected command/args.
• The server supports multiple tools; consult the API reference for details on each endpoint and payload format.