Elysium Desktop Commander

Local-first MCP tools for Codex and other MCP clients on macOS. Version 0.2.0 exposes bounded read-only filesystem tools and a narrow allowlist of process diagnostics over MCP STDIO or an opt-in, bearer-authenticated Streamable HTTP endpoint bound to loopback. It does not contain desktop/browser automation, OAuth, device pairing, or an outbound remote relay.

Requirements

• Node.js 22.19+, 24.11+, or 26+

• npm

• Codex CLI for MCP integration (optional for direct local use)

Related MCP server: DesktopBridge

Install and verify

cd ~/Projects/elysium-desktop-commander
npm ci
npm run check
npm run lint
npm test
npm run build
npm run smoke:mcp
npm run smoke:http

Run locally

npm run mcp

The server uses the current working directory as the default authorized root. Set ELYSIUM_ALLOWED_ROOTS to a platform-separated list of explicitly authorized roots. Set ELYSIUM_AUDIT_LOG to opt into metadata-only audit records. No telemetry is enabled.

Remote MCP endpoint (local loopback only)

After building, start the optional HTTP endpoint with a unique random token of at least 32 bytes:

ELYSIUM_REMOTE_TOKEN='replace-with-a-long-random-secret' npm run start:http

The endpoint listens on 127.0.0.1:8765/mcp and requires Authorization: Bearer …. It refuses non-loopback bind addresses. To reach it remotely, use a supported authenticated HTTPS tunnel or deploy a separate gateway/reverse proxy with TLS and access control. Do not expose the Mac's port directly. This endpoint currently has no OAuth authorization server, device pairing, revocation registry, or outbound relay; it is not a production remote-control deployment and may not be accepted by clients that require OAuth. Use it only with trusted clients that securely store bearer tokens.

Update and uninstall

To update dependencies within the pinned ranges, review package changes, run npm update, then run the full verification steps above. Intentional version changes belong in package.json and package-lock.json together.

To disconnect the server from Codex, run codex mcp remove elysium-desktop-commander. To remove the local checkout, first preserve any work you need, then remove ~/Projects/elysium-desktop-commander yourself. Unregistering the server does not delete the project or its logs.

Codex registration

Only after build and tests pass, register the compiled server:

codex mcp add elysium-desktop-commander -- node "$HOME/Projects/elysium-desktop-commander/dist/server/main.js"

Then inspect with codex mcp list and restart Codex if needed. The server's launch directory is its default authorized root; configure additional roots deliberately in Codex MCP environment settings. Registration in Codex does not provide a ChatGPT remote connector.

Security boundary

The agent runs with the current user's OS privileges. Path roots and the executable allowlist are application guardrails, not a sandbox. The default READ_ONLY profile exposes no file writes, arbitrary shell, process termination, secrets, browser storage, desktop actions, network relay, or public listener. The optional loopback HTTP endpoint exposes the same read-only tools and is disabled unless explicitly started with a strong bearer token. See Security and Threat model.

Capability status

Implemented: health, authorized roots, bounded directory listing, bounded UTF-8 reads, metadata, bounded content/name search, read-only diagnostic commands, process session observation, and authenticated loopback Streamable HTTP. Pending: OAuth, interactive approval, writes, process cancellation, macOS GUI automation, browser adapter, device pairing, outbound relay, and an externally hosted Elysium gateway. See tool inventory, reference audit, and tests.

License

MIT. See LICENSE.