# Computer MCP - AI-assisted install guide

This file is written for an AI assistant setting up **Computer MCP by Agent360**.
Follow it top to bottom. There is **one step only a human can do** - granting two
macOS permissions - and it is called out clearly. Do not claim the setup is
finished until `computer_permissions` confirms it.

## What this server is, in one paragraph

Computer MCP drives macOS itself: it reads the accessibility tree, takes
screenshots, clicks, types, presses buttons, chooses menu items and moves
windows. The source has **30 tools, 14 of them read-only**, no API key, and
no network calls of its own.

<!-- FORBEHOLD -->
> **What you get today, honestly.** `npx @agent360/computer-mcp` currently serves **0.1.0**, which has 12 tools. The 30 tools described here are the source: they are built and tested, but not published yet. Building from source takes about thirty-five seconds if you want them now.
<!-- /FORBEHOLD -->The design premise is that it is safe to leave running: password fields are blacked out in memory
before a screenshot is written to disk, writes go through a consent gate, and
every action lands in a log the server only appends to - every line carries a fingerprint of itself and the one before it, so a removed or edited line breaks the chain and says where that never stores typed text in clear.

## Step 1 - register the server with the client

Claude Code:

```bash
claude mcp add --scope user computer -- npx -y @agent360/computer-mcp@latest
```

OpenAI Codex:

```bash
codex mcp add computer -- npx -y @agent360/computer-mcp@latest
```

Any other client (Cursor, VS Code, Windsurf, Cline) - write this into that
client's MCP config:

```json
{
  "mcpServers": {
    "computer": {
      "command": "npx",
      "args": ["-y", "@agent360/computer-mcp@latest"]
    }
  }
}
```

## Step 2 - pick the mode BEFORE the first run

This is the decision that matters. The default is `allow`, so an agent can be left
running; password managers, terminals, quitting and closing still ask. Set
`CMCP_MODE` in the server's `env` block:

| `CMCP_MODE` | What the agent can do | Use it when |
|---|---|---|
| `readonly` | Only the 14 read tools are listed. The write tools do not exist as far as the model is concerned. | You are evaluating, or the agent only needs to look. **Start here.** |
| `ask` | The first write opens a dialog; one yes grants the session. Password managers ask every single time, terminals and editors once per session. | You want to approve before anything is touched. |
| `allow` | **Default.** Writes proceed without asking. Still logged. Password managers still ask every time, terminals and editors once per session. | Normal use: an agent you can leave running. |

Recommend `readonly` for a first install and say why: nothing can go wrong, and
the user can see the tool list before granting anything.

## Step 3 - THE HUMAN STEP: two macOS permissions

**You cannot do this. A person has to click it.** Ask them, then wait.

1. **System Settings -> Privacy & Security -> Accessibility**
2. **System Settings -> Privacy & Security -> Screen Recording**

**Which app do they grant them to?** macOS attributes these to the *responsible
process*, which depends on how the server was launched. Run from a terminal it is
usually the terminal; launched by an MCP client over `npx` it may be the client.
Tell them honestly: grant it to whichever app the system dialog names, and if no
dialog appears, start with the app that launched the client.

## Step 4 - verify, do not assume

Call `computer_permissions`. It reports each permission separately. Only when
both read as granted is the install finished. If one is missing, say which one
and send the user back to Step 3 - do not retry the tool in a loop.

Then call `computer_screenshot` once. A returned image with both permissions
granted is the real end-to-end proof.

## What this server deliberately does not have

No shell execution, no arbitrary file access, no URL fetching. Each would be a
few lines of code. Do not suggest working around this by pairing it with a shell
server without saying plainly what that combination gives up.

## Reporting back

If macOS behaves differently from the above - for instance if upgrading the
package re-prompts for permissions - that is an unmeasured case the maintainers
want: https://github.com/Agent360dk/computerMCP/issues

Homepage: https://computermcp.dev - MIT licence - macOS only.