update README with corrected MCP config and clarified usage

- 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.
2025-12-31 02:19:58 -06:00 · 2025-10-01 11:49:17 -04:00
parent 37864faef2
commit 671845001c
1 changed files with 87 additions and 39 deletions
--- a/libs/python/mcp-server/README.md
+++ b/libs/python/mcp-server/README.md
@@ -15,13 +15,15 @@
 </h1>
 </div>

-**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)
+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.