remote-mcp

Remote MCP Control Skill

Control remote MCP-enabled machines using the terminator CLI.

Prerequisites

1. Terminator CLI installed: cargo install terminator-cli or npx @mediar-ai/cli
2. MCP endpoint URL from target machine (e.g., http://<IP>:8080/mcp)
3. Auth token (if required): Set via MCP_AUTH_TOKEN env var

---

Basic Usage

# Set auth token if required
export MCP_AUTH_TOKEN="your-token-here"

# Execute a command on remote machine
terminator mcp exec --url "http://<IP>:8080/mcp" run_command '{
  "run": "node -e \"console.log(JSON.stringify({cwd: process.cwd()}))\"",
  "timeout_seconds": 10
}'

---

Common Commands

1. Run Shell Command

terminator mcp exec --url "http://<IP>:8080/mcp" run_command '{
  "run": "tasklist /FI \"IMAGENAME eq chrome.exe\" /FO TABLE",
  "timeout_seconds": 10
}'

2. Run JavaScript

terminator mcp exec --url "http://<IP>:8080/mcp" run_command '{
  "run": "console.log(JSON.stringify({user: process.env.USERNAME, cwd: process.cwd()}))",
  "engine": "javascript",
  "timeout_seconds": 10
}'

3. Check File Exists

terminator mcp exec --url "http://<IP>:8080/mcp" run_command '{
  "run": "dir \"C:\\Users\\vmuser\\Desktop\"",
  "timeout_seconds": 5
}'

4. Get Desktop UI Tree

terminator mcp exec --url "http://<IP>:8080/mcp" get_desktop_elements '{
  "depth": 1
}'

5. Get Process-Specific UI Tree

# Chrome UI tree
terminator mcp exec --url "http://<IP>:8080/mcp" get_desktop_elements '{
  "selector": "process:chrome",
  "depth": 3
}'

6. Take Screenshot

terminator mcp exec --url "http://<IP>:8080/mcp" take_screenshot '{}'

7. Run PowerShell Script

terminator mcp exec --url "http://<IP>:8080/mcp" run_command '{
  "run": "powershell -Command \"Get-Process | Select-Object ProcessName, Id | ConvertTo-Json\"",
  "timeout_seconds": 15
}'

---

MCP Tool Reference

Tool	Description	Args
run_command	Execute shell/JS/Python	{"run": "...", "engine": "javascript", "timeout_seconds": N}
get_desktop_elements	Get UI tree	{"selector": "...", "depth": N}
take_screenshot	Capture screen	{"selector": "..."} (optional)
click_element	Click UI element	{"selector": "process:App >> role:Button && name:OK"}
type_text	Type into element	{"selector": "...", "text": "..."}
press_key	Press keyboard key	{"key": "enter"} or {"key": "ctrl+a"}
wait_for_element	Wait for element	{"selector": "...", "timeout_seconds": N}
open_application	Launch app	{"path": "C:\\path\\to\\app.exe"}

---

run_command Args

Arg	Description
run	Command/code to execute (required unless script_file used)
script_file	Path to script file to execute
engine	Script engine: javascript, typescript, python, node, bun
shell	Shell to use: bash, sh, cmd, powershell, pwsh
env	Environment variables as JSON object
timeout_seconds	Execution timeout

---

Selector Syntax

Operators:

• >> - Chain/descendant (scope into process, then find element)
• && - AND (element must match ALL conditions)
• || - OR (element matches ANY condition)
• ! - NOT (element must NOT match)
• () - Grouping

Examples:

# Scope to process, then find button with specific name
process:chrome >> role:Button && name:Submit

# Window matching both role AND name
role:Window && name:Settings

# Multiple conditions
process:notepad >> role:Edit && visible:true

# OR conditions
role:Button && (name:OK || name:Cancel)

# Complex chain
process:explorer >> role:Window && name:Downloads >> role:ListItem

Selector Types:

• process:NAME - Target specific application (use as chain start)
• role:TYPE - UI Automation role (Button, Edit, Window, Text, ListItem)
• name:TEXT - Element name (supports wildcards: name:*partial*)
• nativeid:ID - Native automation ID
• classname:CLASS - Window class name
• visible:true/false - Filter by visibility
• nth:N - Select nth match (0-indexed)

CRITICAL: For actions (click, type), always scope with process: first!

---

Troubleshooting

"401 Unauthorized"

• Set MCP_AUTH_TOKEN environment variable
• Verify token matches server configuration

"Element not found"

• Element not visible on screen
• Wrong process name (case-sensitive!)
• Take screenshot to see current state

"Connection refused"

• MCP server not running on VM
• Check health: curl http://<IP>:8080/health

---

Example Session

# Set up
export MCP_AUTH_TOKEN="your-token"
export MCP_URL="http://<IP>:8080/mcp"

# 1. Check what's running
terminator mcp exec --url "$MCP_URL" run_command '{"run": "tasklist", "timeout_seconds": 5}'

# 2. Get desktop UI tree
terminator mcp exec --url "$MCP_URL" get_desktop_elements '{"depth": 1}'

# 3. Take screenshot
terminator mcp exec --url "$MCP_URL" take_screenshot '{}'

# 4. Launch an app
terminator mcp exec --url "$MCP_URL" open_application '{"path": "notepad.exe"}'

# 5. Wait for window
terminator mcp exec --url "$MCP_URL" wait_for_element '{"selector": "process:notepad >> role:Window", "timeout_seconds": 10}'

# 6. Type text
terminator mcp exec --url "$MCP_URL" type_text '{"selector": "process:notepad >> role:Edit", "text": "Hello from remote!"}'

# 7. Click a button
terminator mcp exec --url "$MCP_URL" click_element '{"selector": "process:notepad >> role:MenuItem && name:File"}'