terminator + claude

Terminator + Claude: the two install paths nobody distinguishes.

Almost every guide that comes up for this topic shows one command: claude mcp add terminator. That command only covers Claude Code. If you opened the desktop app from claude.ai and tried the same incantation, nothing happened. There are

two distinct install paths

, and the installer that ships in this repo handles twelve clients in total.

claude mcp addclaude_desktop_config.json35 MCP toolsMIT

Matthew Diakonov, Written with AI

Published May 11, 20269 min read

Direct answer (verified 2026-05-11)

Terminator gives Claude the ability to drive real desktop apps by exposing 35 accessibility-API-backed tools through a Model Context Protocol server. There are two install paths. Claude Code: claude mcp add terminator "npx -y terminator-mcp-agent@latest". Claude Desktop: add the mcpServers block to claude_desktop_config.json (path varies by OS, see the next section).

Verified against the install code in crates/terminator-mcp-agent/config.js and the project README. Both paths terminate at the same terminator-mcp-agent process speaking MCP over stdio.

Path 1: Claude Code (the terminal CLI)

Claude Code is the CLI you install from npm as @anthropic-ai/claude-code. It stores MCP servers in ~/.claude.json and ships a subcommand for adding them, so you never touch the file by hand. One line wires Terminator in. The -s user flag installs at user scope, which means every project on the machine sees the server, not just the project you happened to be in when you ran the command.

shell: claude-code-install

# 1. Add the Terminator MCP server to Claude Code
claude mcp add terminator "npx -y terminator-mcp-agent@latest" -s user

# 2. Verify the server is registered
claude mcp list

# 3. Start a session. Terminator's 35 tools are now callable.
claude

# That's the whole install. No JSON. The CLI writes
# to ~/.claude.json (user scope) under "mcpServers".

Path 2: Claude Desktop (the chat app from claude.ai)

Claude Desktop is the GUI app you download from Anthropic. It loads MCP servers from a JSON file at startup. There is no claude mcp add equivalent inside the app, so you either edit the file by hand or let Terminator's installer write it for you. The exact path depends on the OS, and this is the bit no other write-up makes explicit:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Those paths come from platformPaths at lines 25 through 46 of crates/terminator-mcp-agent/config.js. The directory may not exist yet; the installer creates it on first run.

claude_desktop_config.json

// Open Settings -> Developer -> "Edit Config" in Claude Desktop,
// or open the file directly:
//
//   Windows: %APPDATA%\Claude\claude_desktop_config.json
//   macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
//
// Add Terminator under mcpServers, save, restart Claude Desktop.

{
  "mcpServers": {
    "terminator-mcp-agent": {
      "command": "npx",
      "args": ["-y", "terminator-mcp-agent@latest"],
      "env": {
        "LOG_LEVEL": "info",
        "RUST_BACKTRACE": "1"
      }
    }
  }
}

Or, if you would rather not touch the JSON, the installer can do it for you and pick up the right path on your OS. Press Enter at the prompt and Claude Desktop is the default selection.

npx -y terminator-mcp-agent@latest --add-to-app

From supportedClients at lines 260 through 273 of config.js. Claude is the default fallback in getConfigPath: if you pass no argument, line 107 normalises the client to "claude".

What ends up on the wire

Both install paths boot the same terminator-mcp-agent process. The client speaks MCP over stdio (or HTTP, with -t http), and the agent dispatches each tool call into the platform's accessibility API. Here is the shape of a single user request through the stack:

claude_code -> mcp_agent -> os

The point is that Claude itself doesn't know about UI Automation or AXUIElement. It calls a tool by name (one of the 35 #[tool(...)] macros in crates/terminator-mcp-agent/src/server.rs) with structured arguments, and the agent does the platform work. That is why the same install commands work whether you're on a Windows VM driving an installer or on macOS clicking through a native preference pane.

The two configs, side by side

If you have ever wired both Claude Code and Claude Desktop, you know the configs look almost identical at the mcpServers level but live in different files. Toggle below to see what each one writes.

Same server, two config homes

# 1. Add the Terminator MCP server to Claude Code
claude mcp add terminator "npx -y terminator-mcp-agent@latest" -s user

# 2. Verify the server is registered
claude mcp list

# 3. Start a session. Terminator's 35 tools are now callable.
claude

# That's the whole install. No JSON. The CLI writes
# to ~/.claude.json (user scope) under "mcpServers".

-82% cli vs json

Walk it through

Four steps cover both paths. The two middle steps are where Claude Code and Claude Desktop diverge; the first and last steps are the same.

1
Pick which Claude you're using
Claude Code (the terminal CLI) and Claude Desktop (the GUI app from claude.ai) read MCP servers from different places. Pick one before you copy any command. Both work; the install paths are different.
2
Wire the server
Claude Code: run `claude mcp add terminator "npx -y terminator-mcp-agent@latest"`. Claude Desktop: edit claude_desktop_config.json and add the mcpServers block. The installer can do the JSON edit for you with `npx -y terminator-mcp-agent@latest --add-to-app`.
3
Restart the client
Claude Code picks up the new server on the next `claude` invocation. Claude Desktop needs a quit-and-relaunch from the system tray (Windows) or the dock menu (macOS) so the renderer process re-reads the config file.
4
Confirm the 35 tools are visible
Ask Claude what tools it can see from the terminator server. You should get back open_application, click_element, type_into_element, press_key, get_window_tree, capture_screenshot, execute_sequence, run_command, and 27 more. If you only see a few or get nothing, the server failed to start; check the MCP logs path below.

Verify the round trip

After either install, the cheapest verification is to ask Claude what it can see, then drive a known app. Notepad is a safe target on Windows; TextEdit works the same way on macOS.

post-install smoke test

If the tool list comes back empty, the server didn't start. The MCP log directory is %LOCALAPPDATA%\claude-cli-nodejs\Cache\<encoded-cwd>\mcp-logs-terminator-mcp-agent\ on Windows, and the equivalent under ~/.local/share/claude-cli-nodejs/Cache/ on macOS and Linux. Tail the most recent .txt file there and you will see the startup banner, the MCP handshake, and the first tool dispatch.

What about the other 10 clients?

Claude Code and Claude Desktop are the most common entry points, but the same MCP server installs into every major MCP-aware client. The installer writes to the appropriate config file or shells out to the client's own CLI (VS Code uses code --add-mcp; everything else edits JSON).

Defined in clientPaths and supportedClients inside crates/terminator-mcp-agent/config.js

Every client the installer knows about

Claude Code

claude mcp add CLI. Writes to ~/.claude.json.

Claude Desktop

claude_desktop_config.json. Default in --add-to-app.

Cursor

~/.cursor/mcp.json. Has a deeplink install URL.

VS Code

Uses the `code --add-mcp` CLI, not a file.

VS Code Insiders

Same as VS Code, via `code-insiders --add-mcp`.

Windsurf

~/.codeium/windsurf/mcp_config.json.

Cline

VS Code globalStorage path under saoudrizwan.claude-dev.

RooCode

VS Code globalStorage under rooveterinaryinc.roo-cline.

Witsy

Application Support/Witsy/settings.json.

Enconvo

~/.config/enconvo/mcp_config.json.

BoltAI

~/.boltai/mcp.json.

Amazon Q / Bedrock

~/.aws/amazonq/mcp.json or Amazon Bedrock Client/mcp_config.json.

Why a separate install at all

Anthropic already ships a first-party computer use tool (computer_20251022): screenshot in, pixel coordinates out, one Anthropic round trip per click. That works, but every click costs a vision pass and an API call. If you are running a 20-step workflow inside an enterprise app, that is twenty screenshots and twenty round trips and a lot of room for the model to pick a slightly wrong pixel and ruin the run.

Terminator's MCP server gives Claude a different set of hands. The tools resolve selectors like role:Button && name:Save against the OS accessibility tree locally, in single-digit milliseconds, with no screenshot in flight. The model still reasons; it just doesn't have to look at pixels to act. That trade is what the second install path unlocks, and it is the reason this page exists: most write-ups stop at the one-liner and leave readers who are running Claude Desktop with no idea why nothing happened.

Wiring this into a real product?

If you are giving Claude desktop hands inside a customer-facing workflow, we can review your selector strategy, the failure modes you will hit, and whether the right tool here is the 35-tool MCP or one big execute_sequence call. Book 30 minutes with Matt.

Common questions

Does Terminator only work with Claude, or can other models drive it too?

Terminator's MCP agent is a standard Model Context Protocol server, so any MCP-aware client can call it. The package handles 12 named clients in its `--add-to-app` installer (Cursor, Claude Desktop, VS Code, VS Code Insiders, Windsurf, Cline, RooCode, Witsy, Enconvo, BoltAI, Amazon Bedrock, Amazon Q) and Claude Code is a 13th via the `claude mcp add` CLI. Anything else that speaks MCP can point at the same `npx -y terminator-mcp-agent@latest` command and use the 35 tools without changes.

What's the actual difference between Claude Code and Claude Desktop for this?

Claude Code is Anthropic's terminal CLI: you install it with `npm install -g @anthropic-ai/claude-code` and talk to it from your shell. It stores MCP servers in `~/.claude.json` and you add them with `claude mcp add`. Claude Desktop is the GUI app from claude.ai: it stores MCP servers in `claude_desktop_config.json` at a platform-specific path. Same MCP protocol, two different config surfaces. Terminator's installer covers both; the one-liner you see everywhere only covers the first.

Where exactly does claude_desktop_config.json live on each OS?

Windows: `%APPDATA%\Claude\claude_desktop_config.json` (usually `C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json`). macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`. Linux: `~/.config/Claude/claude_desktop_config.json`. These paths are built from `os.homedir()` and `process.env.APPDATA` inside `crates/terminator-mcp-agent/config.js` lines 25 through 46. The file is JSON, the merge is shallow on `mcpServers`, and the installer creates the parent directory if it doesn't exist.

Why is Claude the default in the `--add-to-app` installer?

Line 107 of `config.js`: `const normalizedClient = client ? client.toLowerCase() : "claude";`. If you run the installer without specifying a client, it falls back to Claude Desktop. The reason is historical: Claude Desktop was the first MCP-enabled chat app to ship, so the installer was written against it first, and the default never moved. Practically it means a developer who runs `npx -y terminator-mcp-agent@latest --add-to-app` and presses Enter ends up with a working Claude Desktop install.

What does Terminator give Claude that Anthropic's built-in computer-use tool doesn't?

Anthropic's `computer_20251022` tool is a screenshot-in, pixel-coordinate-out loop: every action costs a vision round trip and an Anthropic API call. Terminator exposes 35 selector-based tools so Claude can click by accessibility role and name (`role:Button && name:Save`), resolved against the OS accessibility tree locally. Latency drops from hundreds of milliseconds per click to single-digit milliseconds. The tradeoff is that Terminator only works on apps that expose accessibility data, which on Windows is almost everything via UI Automation, and on macOS is most native apps via AXUIElement.

Where do the MCP server logs live so I can debug a failed Claude session?

Windows: `%LOCALAPPDATA%\claude-cli-nodejs\Cache\<encoded-project-path>\mcp-logs-terminator-mcp-agent\*.txt`. macOS/Linux: `~/.local/share/claude-cli-nodejs/Cache/<encoded-project-path>/mcp-logs-terminator-mcp-agent/*.txt`. The `<encoded-project-path>` segment is your current working directory with slashes percent-encoded. To enable verbose logging, set `LOG_LEVEL=debug` and `RUST_BACKTRACE=1` in the server's env block in `claude_desktop_config.json` (or the equivalent in Claude Code's `~/.claude.json`).

Will the install touch other MCP servers I already have configured?

The merge is shallow on the `mcpServers` object: existing servers are preserved, and `terminator-mcp-agent` is added or overwritten as a single key. See `writeConfigFile` in `config.js` lines 217 through 251: the existing config is read, spread into `mergedConfig`, and the new config is spread on top. Anything you have under `globalShortcut` or other top-level keys is untouched. If you want to remove Terminator later, delete the `terminator-mcp-agent` key from `mcpServers` and restart the client.

What platforms does the install actually run on?

Node 18 or newer for the npx invocation. The runtime currently ships Windows binaries through the `terminator-mcp-win32-x64-msvc` and `terminator-mcp-win32-arm64-msvc` optional dependencies in the npm package. macOS support exists at the core Rust level via AXUIElement and is exposed through `app.mediar.ai`; Linux uses AT-SPI2 and is wired through the same MCP interface. Claude Code runs everywhere Node runs; Claude Desktop runs on Windows and macOS. The same `npx -y terminator-mcp-agent@latest` command works for all clients on all supported platforms, the installer detects the OS at runtime.

Can I run Terminator's MCP server over HTTP instead of stdio?

Yes. The agent accepts `-t http` to switch from stdio to an HTTP transport, then exposes `POST /mcp` for tool calls, `GET /health` as a liveness check, and `GET /status` as a busy probe (200 idle, 503 busy). Concurrency is `MCP_MAX_CONCURRENT` (default 1). This is how the `remote-mcp` skill in the Terminator repo lets Claude drive a remote VM: the VM runs the agent in HTTP mode, Claude on your laptop calls `terminator mcp exec --url http://<vm-ip>:8080/mcp <tool> '<json>'`, and the tool runs on the VM. Set `MCP_AUTH_TOKEN` to require a bearer token.

What's the smallest workflow that proves the install is working?

After wiring the MCP server, start Claude (Code or Desktop) and say: "open Notepad and type 'hello from claude'". Claude should issue two tool calls: `open_application` with `{"app_name": "notepad"}`, then `type_into_element` with a selector like `role:Document` or `role:Edit` and the text. If you see those two calls and the text shows up in the Notepad window, the round trip is healthy. If Claude says it doesn't have the tools, the server didn't load; check the MCP log directory above.

Deeper dives on specific parts of the Claude + Terminator wiring.