From 671845001cbe581e10544c3c868f46c75dcb86c2 Mon Sep 17 00:00:00 2001 From: Adam <62897873+YeIIcw@users.noreply.github.com> Date: Wed, 1 Oct 2025 11:49:17 -0400 Subject: [PATCH] update README with corrected MCP config and clarified usage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Updated the README to clarify how to configure cua-mcp-server for Claude Desktop and other MCP clients. - Fixed the example development configuration to use an absolute/expanded path rather than `~`, preventing issues with Claude’s sandboxed execution. - Aligned instructions with the current start_mcp_server.sh behavior, ensuring the correct virtual environment and PYTHONPATH are always set. - Improved wording for consistency across installation, development, and usage sections. --- libs/python/mcp-server/README.md | 126 +++++++++++++++++++++---------- 1 file changed, 87 insertions(+), 39 deletions(-) diff --git a/libs/python/mcp-server/README.md b/libs/python/mcp-server/README.md index 08aa763a..0ed79435 100644 --- a/libs/python/mcp-server/README.md +++ b/libs/python/mcp-server/README.md @@ -15,13 +15,15 @@ -**cua-mcp-server** is a MCP server for the Computer-Use Agent (CUA), allowing you to run CUA through Claude Desktop or other MCP clients. +# cua-mcp-server -### Get started with Agent +cua-mcp-server is an MCP server for the Computer-Use Agent (CUA). It enables CUA to run through MCP clients such as Claude Desktop and Cursor. ## Prerequisites -Cua MCP Server requires [lume](https://github.com/trycua/cua/blob/main/libs/lume/README.md#install) to be installed. +- Install lume: https://github.com/trycua/cua/blob/main/libs/lume/README.md#install +- Python 3.10+ +- pip, venv, setuptools ## Install @@ -31,52 +33,98 @@ Download and run the installation script: curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/python/mcp-server/scripts/install_mcp_server.sh | bash ``` -You can then use the script in your MCP configuration like this: - -```json -{ - "mcpServers": { - "cua-agent": { - "command": "/bin/bash", - "args": ["~/.cua/start_mcp_server.sh"], - "env": { - "CUA_MODEL_NAME": "anthropic/claude-3-5-sonnet-20241022" - } - } - } -} -``` - -## Development - -Use this configuration to develop with the cua-mcp-server directly without installation: +Add this to your MCP client configuration: ```json { "mcpServers": { "cua-agent": { - "command": "/bin/bash", - "args": ["~/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"], - "env": { - "CUA_MODEL_NAME": "huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B" - } + "command": "/usr/bin/env", + "args": [ + "bash", "-lc", + "export CUA_MODEL_NAME='anthropic/claude-3-5-sonnet-20241022'; ~/.cua/start_mcp_server.sh" + ] } } } ``` -This configuration: -- Uses the start_mcp_server.sh script which automatically sets up the Python path and runs the server module -- Works with Claude Desktop, Cursor, or any other MCP client -- Automatically uses your development code without requiring installation +## Development (run from a local checkout) -Just add this to your MCP client's configuration and it will use your local development version of the server. +Use an absolute path to the repository root in the arguments below. -## Docs +```json +{ + "mcpServers": { + "cua-agent": { + "command": "/usr/bin/env", + "args": [ + "bash", "-lc", + "export CUA_MODEL_NAME='huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B'; /Users/your-username/Documents/GitHub/cua/libs/python/mcp-server/scripts/start_mcp_server.sh" + ] + } + } +} +``` -- [Installation](https://trycua.com/docs/libraries/mcp-server/installation) -- [Configuration](https://trycua.com/docs/libraries/mcp-server/configuration) -- [Usage](https://trycua.com/docs/libraries/mcp-server/usage) -- [Tools](https://trycua.com/docs/libraries/mcp-server/tools) -- [Client Integrations](https://trycua.com/docs/libraries/mcp-server/client-integrations) -- [LLM Integrations](https://trycua.com/docs/libraries/mcp-server/llm-integrations) \ No newline at end of file +Notes: +- Replace `/Users/your-username/Documents/GitHub/cua` with the absolute path to your clone. +- The script sets `PYTHONPATH` for local libs and runs the server module. + +## Quick Start + +After configuring your MCP client, restart it and invoke one of these tools: + +- Take a screenshot + +```json +{ + "tool": "screenshot_cua", + "args": {} +} +``` + +- Run a task + +```json +{ + "tool": "run_cua_task", + "args": { "task": "Open Safari and search for University of Toronto" } +} +``` + +Expected results: +- Assistant messages streamed during execution +- A final screenshot image + +## Documentation + +- Installation: https://trycua.com/docs/libraries/mcp-server/installation +- Configuration: https://trycua.com/docs/libraries/mcp-server/configuration +- Usage: https://trycua.com/docs/libraries/mcp-server/usage +- Tools: https://trycua.com/docs/libraries/mcp-server/tools +- Client Integrations: https://trycua.com/docs/libraries/mcp-server/client-integrations +- LLM Integrations: https://trycua.com/docs/libraries/mcp-server/llm-integrations + +## Troubleshooting + +Server reports disconnected in MCP client: +- Use an absolute path in the `args` command. +- Launch via `/usr/bin/env bash -lc` so the shell initializes and expands paths. +- Run the script manually to verify: + ```bash + /usr/bin/env bash -lc '/Users/your-username/Documents/GitHub/cua/libs/python/mcp-server/scripts/start_mcp_server.sh' + ``` + +pip not found in venv: +```bash +python3 -m ensurepip --upgrade +python3 -m pip install -U pip setuptools wheel +``` + +Pydantic schema error related to Image: +```bash +python3 -m pip install -U "mcp>=1.2.0" "fastmcp>=0.4.7" "pydantic>=2.7,<2.12" +``` + +If issues persist, capture logs from your MCP client and the server startup script for diagnosis.