LCU Auto

lcu-auto mcp

Expose the installed LCU runtime as a local MCP server. Use lcu-auto mcp --url http://127.0.0.1:8789/mcp when local clients should share a broker with remote clients.

Early-stage software (0.x). This package supplies the adapter, not the desktop-control engine. Install upstream LCU and its required official ChatGPT desktop app separately. Native-app consent is automatically answered locally: by default, an offered Always allow choice becomes a persistent grant. Use only with clients you trust.

Why this exists

Some MCP clients can call tools but cannot display LCU's app-approval prompts. Remote clients can also create a new MCP connection for each tool call, losing JavaScript bindings or consuming a new runtime slot every time.

LCU Auto handles recognized native-app consent locally, keeps computer-use state across related calls, and separates lightweight tool discovery from actual desktop execution. It exposes only js and js_reset; your client still decides whether to approve a tool invocation.

Related MCP server: Remote Link Local MCP

Install

You need Node.js 22.14 or later. Install the CLI from npm (Bun is not required):

npm install --global lcu-auto
lcu-auto --version
lcu-auto doctor

--version verifies the installed CLI. doctor additionally checks for an upstream LCU installation; if it is not installed, follow the upstream setup instructions below. For a source installation, also install Bun 1.4.3 and run:

git clone https://github.com/yoyooyooo/lcu-auto.git
cd lcu-auto
bun install --frozen-lockfile
bun run build
bun run shim:install
lcu-auto --version
lcu-auto doctor

doctor checks that the installed LCU adapter can be found. It does not click an app, grant OS permissions, or prove that screenshots work. A successful check prints LCU adapter found.

Follow upstream LCU installation for its runtime and permissions. By default, this CLI looks under ~/.local/share/lcu on macOS and /opt/lcu on Linux. Set --lcu-dir or LCU_AUTO_PREFIX for a different installation. A prefix containing current/, or a release directory containing adapters/, is accepted.

Platform boundary

The CLI uses Node.js and platform-aware paths. CI exercises its protocol, configuration, package and CLI checks on macOS, Linux and Windows. Service definitions are available for launchd, systemd user services and Windows Task Scheduler.

Desktop control is a separate dependency. Upstream LCU lists Apple Silicon macOS and compatible Linux/X11 desktops; Windows is a candidate, not a supported desktop backend in this release. This project's live desktop verification is on Apple Silicon macOS. Linux desktop execution and non-macOS service installation are not claimed as live-verified. See compatibility.

First connection

Add this stdio entry to your MCP client's configuration:

{
  "mcpServers": {
    "lcu-auto": {
      "command": "lcu-auto",
      "args": ["mcp"]
    }
  }
}

An npm installation uses your npm global executable directory; check that lcu-auto --version works on PATH. Only the source shim:install command writes to ~/.local/bin (or %LOCALAPPDATA%\lcu-auto\bin on Windows). Use the absolute path to the installed command when a GUI client does not inherit your shell's PATH. The client should list exactly js and js_reset. mcp itself does not print a welcome message: stdout is reserved for MCP.

Ask the client to select a harmless test app, read its state, and then perform a separate input call. Verify the visible result. Do not begin with a messaging app, an account-setting page or a valuable document.

LCU's instructions describe the cua API. The first js call selects an app or reads the inventory; later calls can reuse the binding only when they share the same execution context. A new transport without a stable conversation identifier may start a fresh JavaScript REPL. Only recognized native-app consent is automated. Unknown requests are cancelled, and LCU's host-app restrictions and operating-system permissions remain in force.

Shared broker

A broker lets local and remote clients use the same desktop queue. Create a local credential, start the server, then point local clients at it:

lcu-auto token
lcu-auto serve

In another terminal or in the MCP client's command configuration:

lcu-auto mcp --url http://127.0.0.1:8789/mcp

The credential is read from the local configuration directory; it is not placed in the MCP config or printed. All HTTP routes require authentication. The broker binds to loopback only.

For an opt-in user service:

lcu-auto service install
lcu-auto service start
lcu-auto service status

Installation does not start the service. Stop an existing foreground server before starting the managed service. stop and restart refuse to disconnect clients unless you explicitly pass --force-disconnect. Installation points to the current installed CLI; reinstall the definition after moving the installation. Service management explains platform limitations and recovery.

Remote access

For private Tailscale networks, use Tailscale Serve (tailnet-only HTTPS) with a separate bearer credential. The broker still binds to loopback and Cloudflare Access remains independent:

lcu-auto token --token-file ~/.config/lcu-auto/remote.token
lcu-auto serve --tailnet-origin https://mini.example-tailnet.ts.net:9443 \
  --remote-token-file ~/.config/lcu-auto/remote.token
tailscale serve --bg --https=9443 8789

Configure a remote HTTP MCP client with the Serve URL ending in /mcp and an Authorization: Bearer <remote-token> header. Do not commit the credential or expose the Serve port via Funnel. For a managed service, use lcu-auto service install with the same --tailnet-origin and --remote-token-file flags. Tailnet deployment and security explains setup, token lifecycle and caveats.

Use a named Cloudflare Tunnel and Access Managed OAuth, then start the broker with an Access configuration file. The origin verifies the signed Access assertion instead of trusting an email header. Local bearer credentials do not authenticate requests addressed to the public hostname.

Follow the complete remote deployment guide. It covers prerequisites, OAuth discovery, callback registration, origin validation and verification. A tunnel alone is not authentication. No tunnel, account policy or DNS record is created automatically by installing this package.

State and safety

Consecutive calls within the same execution context retain one computer-use control turn. Successful tool returns do not end it. For ChatGPT-style short-lived clients, the broker correlates state only if the client provides a stable conversation identifier together with its verified identity; the identifier is not authentication. Other clients use connection-owned state. A new connection without a correlation identifier may use an entirely new REPL.

For scheduled/background tasks that may reconnect for each call, follow LCU's first-call setup instructions, then write subsequent js calls so they do not depend on prior JavaScript variables: reacquire the target app, observe fresh UI state and perform related actions in the same call where practical. If an earlier action might already have taken effect, observe before retrying; never blindly repeat desktop side effects. See lost bindings.

Discovery does not reserve an execution runtime. Idle runtimes are bounded and reclaimed; running actions are not evicted. Cancellation, reset and shutdown clean up before another queued operation starts. A timeout or lost response can conceal an action that already happened, so observe the desktop before retrying.

If a context becomes closed or broken, explicitly call js_reset: it replaces the owned LCU process without replaying previous actions, even when an HTTP reconnect still points to the failed context. This also refreshes runtime state after reinstalling the desktop app. It does not grant OS permissions. See recovery.

The queue serializes individual calls, not an entire multi-step task. Avoid two agents editing the same window. Screenshots and accessibility text can contain private information and are returned to your MCP client. The package does not send telemetry or retain tool results in its production logs. LCU and your client have their own behavior and terms.

The default --scope always can persist app grants in upstream LCU. --scope session or --scope once reduces the maximum requested persistence but does not revoke old grants. Browser-extension access is opt-in and requires exact site origins. See the security model.

Commands and development

mcp, serve, token, doctor, config paths and service are the public command groups. Run lcu-auto <command> --help for flags, shell completions and errors. The old connect, stdio and http spellings remain migration aliases; new integrations should use mcp and serve.

bun install --frozen-lockfile
bun run check
bun run pack:check

The default tests need no installed LCU, GUI, cloud account or private credential. Live tests are explicit and separate. Contributing describes the checks and bilingual documentation policy; release operations describes immutable tags and npm trusted publishing.

CLI reference · Troubleshooting · Architecture · Changelog · Report a vulnerability

MIT licensed. This project is not affiliated with OpenAI or Amont Labs. LCU is installed separately; proprietary desktop runtime assets are not redistributed. See third-party notices.