OmniCommanderMCP

Omni Commander MCP is a cross-platform, local-first MCP agent that gives an authorized AI client broad control over a Windows, macOS, or Linux computer.

It combines two control planes in one auditable server:

1. System/CLI control: files, shell, persistent terminals, processes, services, packages, network requests, firewall, scheduled tasks, Git, archives, disks, users, logs, clipboard, and power/session operations.
2. Computer use: screenshots returned as MCP images, monitor/window/application control, mouse, keyboard, accessibility-tree inspection, local OCR, text-coordinate discovery, and observe-act-observe loops.

The server can run locally over stdio, over an authenticated loopback/private Streamable HTTP endpoint, or privately from ChatGPT web through OpenAI Secure MCP Tunnel without opening inbound firewall ports.

This project intentionally has powerful tools. --profile=full is equivalent to granting the connected MCP client an interactive desktop and terminal under the OS account that launches Omni Commander. Read SECURITY.md.

Current status

The current main branch exposes 84 MCP tools. Version 0.2.0 is the package baseline, with 0.3 development active on main:

• Windows, macOS, and Linux adapters.
• MCP stdio and Streamable HTTP transports.
• OpenAI Secure MCP Tunnel setup scripts.
• Persistent process sessions with stdin and paginated output.
• Native file-watch sessions with bounded retention and cursor pagination.
• Direct image-returning screen observation.
• Multi-step autonomous computer-use sequences.
• OCR-based find text and click text workflows.
• Windows UI Automation, macOS Accessibility, and Linux AT-SPI discovery adapters.
• Safe/full policy profiles, SSRF controls, path canonicalization, and JSONL audit logs.
• Cross-platform CI, type checking, integration tests, and production builds.

Tool catalog

Area	Tools
Configuration	config_get, config_set
Filesystem/search	fs_read, fs_read_many, fs_write, fs_patch, fs_list, fs_mkdir, fs_copy, fs_move, fs_delete, fs_stat, fs_hash, fs_search, fs_watch_start, fs_watch_events, fs_watch_stop, fs_watch_sessions
Terminal/processes	shell_exec, process_start, process_output, process_input, process_terminate, process_sessions, process_list, process_kill
Computer observation	desktop_capabilities, monitor_list, desktop_screenshot, desktop_screenshot_file, computer_observe, screen_ocr, screen_find_text, accessibility_snapshot
Computer actions	mouse_move, mouse_click, mouse_drag, mouse_scroll, cursor_position, keyboard_type, keyboard_key, keyboard_hotkey, computer_sequence, computer_act_and_observe, computer_click_text, accessibility_invoke
Apps/windows	application_launch, application_close, window_list, window_control, desktop_open
OS administration	privilege_status, service_list, service_control, package_manager_detect, package_manage, disk_info, user_group_list, installed_applications, scheduled_task_list, scheduled_task_manage, firewall_status, firewall_rule, system_logs, power_control
System/clipboard/env	system_info, env_get, env_set, clipboard_read, clipboard_write
Network	http_request, http_download
Git	git_status, git_diff, git_log, git_stage, git_commit, git_branch, git_checkout, git_remote_sync, git_clone
Archives	archive_list, archive_create, archive_extract

Anything not represented by a structured tool can still be performed through shell_exec or a persistent process_start session when the launching OS account has permission.

Install

Requirements:

• Node.js 20 or later.
• Git.
• Optional desktop/OCR dependencies listed below.

git clone https://github.com/kaannsaydamm/OmniCommanderMCP.git
cd OmniCommanderMCP
npm ci
npm run check
npm run build

Install optional computer-use dependencies:

# macOS or Linux
./scripts/install-desktop-deps.sh

# Windows; built-in APIs cover core computer use.
# Add -InstallTesseract for OCR.
./scripts/install-desktop-deps.ps1 -InstallTesseract

Run locally

Safe profile:

node dist/index.js --profile=safe

Full profile:

node dist/index.js --profile=full

MCP client example:

{
  "mcpServers": {
    "omni-commander": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/OmniCommanderMCP/dist/index.js",
        "--profile=full"
      ],
      "env": {
        "OMNI_AUDIT_ENABLED": "true"
      }
    }
  }
}

Connect ChatGPT web to your computer

The recommended remote path is OpenAI Secure MCP Tunnel. tunnel-client runs on your computer, starts Omni Commander over stdio, and makes only outbound HTTPS connections to OpenAI. The MCP server does not need a public listener.

1. Build Omni Commander

npm ci
npm run build

2. Create an MCP tunnel

Create a tunnel in OpenAI Platform tunnel settings and obtain:

• A tunnel_id.
• A runtime API key for tunnel-client.
• Tunnels Read + Use permission; tunnel creation/editing additionally needs Manage.

Download the current tunnel-client from the OpenAI Platform tunnel page or the official openai/tunnel-client releases.

3. Configure the local tunnel profile

macOS/Linux:

CONTROL_PLANE_API_KEY="sk-..." ./scripts/setup-openai-tunnel.sh tunnel_0123456789abcdef0123456789abcdef

Windows PowerShell:

$env:CONTROL_PLANE_API_KEY = "sk-..."
./scripts/setup-openai-tunnel.ps1 -TunnelId "tunnel_0123456789abcdef0123456789abcdef" -SecurityProfile full

The scripts configure this local MCP command:

node /absolute/path/OmniCommanderMCP/dist/index.js --profile=full

4. Run the tunnel

tunnel-client doctor --profile omni-commander --explain
tunnel-client run --profile omni-commander

Keep it running while ChatGPT uses the computer. The tunnel client exposes loopback health/readiness/metrics endpoints and a local /ui operator page.

5. Add it in ChatGPT

Enable ChatGPT developer mode, open Settings → Plugins, create a developer-mode app, select Tunnel as the connection, and choose the tunnel. The tunnel must be associated with the target ChatGPT workspace.

See docs/REMOTE_CHATGPT.md for startup-service templates and troubleshooting.

Streamable HTTP mode

Stdio + Secure MCP Tunnel is preferred for ChatGPT. For local/private integrations, Omni Commander can also expose MCP over Streamable HTTP:

node dist/index.js --http --host=127.0.0.1 --port=8787 --profile=full

Endpoint:

http://127.0.0.1:8787/mcp

Health endpoints:

/healthz
/readyz

Binding outside loopback requires a bearer token:

OMNI_HTTP_TOKEN="a-long-random-secret" \
node dist/index.js --http --host=0.0.0.0 --port=8787 --allowed-hosts=omni.internal.example --profile=full

This fixed bearer mode is for controlled private deployments. A public internet deployment should use a proper OAuth authorization server, TLS, strict host validation, and an external reverse proxy. Do not expose full-profile Omni Commander anonymously.

Autonomous computer-use pattern

A reliable loop is:

1. computer_observe to receive a fresh screenshot.
2. accessibility_snapshot or screen_find_text when semantic targeting is possible.
3. computer_act_and_observe for one action plus a fresh screenshot.
4. Repeat until the task is verified complete.

For deterministic multi-step operations, use computer_sequence. For visible text, computer_click_text captures, OCRs, clicks the chosen occurrence, and returns the post-click screen.

See docs/COMPUTER_USE.md.

File-watch sessions

Use fs_watch_start for a file or directory, then poll fs_watch_events with the returned session ID. Event cursors are monotonically increasing; pass the previous nextCursor as the exclusive after cursor. Buffers are finite (maxWatchEvents), and truncatedBeforeCursor reports when older events were evicted before the requested cursor. Call fs_watch_stop when observation is complete.

Recursive native watching depends on the host platform and filesystem. Unsupported combinations return an explicit error instead of reporting a successful session.

Platform support

Windows

• Built-in PowerShell, .NET, Win32, Windows UI Automation, service, registry/task/firewall tooling.
• Run Omni Commander at the same elevation level as applications it must control.
• A non-elevated process cannot reliably manipulate elevated windows because of Windows integrity levels.
• Tesseract is optional for OCR.

macOS

• screencapture, AppleScript/System Events, open, launchctl, and optional cliclick.
• Grant Accessibility permission for keyboard/window control.
• Grant Screen Recording permission for screenshots.
• Install optional dependencies with Homebrew.

Linux

• X11: xdotool, wmctrl, xrandr, screenshot and clipboard utilities.
• Wayland: screenshots can use grim; input control depends on compositor security and available tools.
• Accessibility uses Python AT-SPI (pyatspi).
• Headless service sessions cannot control a graphical desktop unless attached to the active user session and display bus.

Security profiles

safe (default)

• Filesystem paths restricted to configured roots.
• Common catastrophic shell patterns blocked.
• Private and loopback HTTP targets blocked.
• Environment values hidden.
• Lower output and file-size limits.
• Audit logging enabled.

full

• All filesystem paths allowed by the OS account.
• No Omni Commander command-pattern blocklist.
• Private/loopback network and environment access enabled.
• OS administration mutation tools enabled.
• Higher finite I/O limits.

full does not bypass ACLs, UAC, sudo, TCC, endpoint security, sandboxing, display-server boundaries, or application permissions.

Configuration

Precedence:

profile defaults < config JSON < environment < CLI < config_set

Default configuration:

~/.omni-commander/config.json

Default audit log:

~/.omni-commander/audit.jsonl

Important environment variables are documented in .env.example.

Development and validation

npm run typecheck
npm test
npm run build

The integration test connects an MCP client through an in-memory transport and verifies that the complete terminal, desktop, accessibility, network, developer, and OS-admin tool surface is discoverable.

CI executes typecheck, tests, and build on Windows, macOS, and Ubuntu with Node.js 20 and 22.

Architecture and roadmap

• Architecture
• Computer use
• ChatGPT remote connection
• Roadmap
• Security policy

License

MIT