Moonlight MCP Plugin

Moonlight is a macOS local gateway that exposes your Mac's files, projects, processes, and native automation to ChatGPT as MCP tools — for ChatGPT web, ChatGPT desktop, and ChatGPT computer use. It connects through the official OpenAI Secure MCP Tunnel (outbound HTTPS only, Desktop loopback HTTP MCP, no public port opened).

This is a fork of lnwjud by Adisorn NM — the Windows runtime surface is removed and the project is rebranded for the macOS + ChatGPT ecosystem. Credit to the original author for the groundwork; see License.

Quick start

1. Install the app

1. Download the DMG (arm64 or x64) from Releases.

2. Drag Moonlight into /Applications and launch it.

3. Releases are unsigned: right-click the app → Open (or xattr -d com.apple.quarantine /Applications/Moonlight.app). Verify with the published SHA256SUMS.txt / PROVENANCE.json.

4. Add the project folder ChatGPT should work on (Projects page).

5. Grant Screen Recording and Accessibility when prompted for native automation.

No system Node.js needed — the app bundles its own runtime.

2. Connect ChatGPT

1. In OpenAI Platform: create a tunnel, create a runtime API key (Tunnels Read + Use).

2. In Moonlight: Settings → OpenAI Secure MCP Tunnel → save key, paste tunnel ID, Configure Tunnel, Start Tunnel. The tunnel targets the Desktop loopback HTTP MCP (sample_mcp_remote_no_auth profile), not a separate headless runtime.

3. In ChatGPT web/desktop (Developer mode): Plugins → add connection → Tunnel → pick the tunnel.

4. In ChatGPT computer use: attach the same tunnel connection so the agent can operate your Mac's files and UI.

5. Confirm that the default runtime exposes 192 tools (or 198 when Codex delegation is explicitly enabled) and run a read-only smoke test before trying writes.

Use Moonlight to list registered workspaces, show Git status for the selected project, and summarize the top-level project tree. Do not modify anything.

Related MCP server: ToolPiper

Features

• Workspace & files — register projects; search, read, edit files with paging and persistent indexing

• Git — status, diff, log, and policy-checked execution

• Processes — owned process lifecycle with bounded logs, timeout, cancellation

• macOS native — accessibility, input, window control, screen capture, notifications, clipboard, file dialogs, audio, scheduler (launchd)

• Browser — managed Chrome / CDP automation with Set-of-Marks annotated observations

• Durable goals — goal continuation with lease fencing and scheduled handoff

• Extensible — local skill discovery, child MCP servers, compound/parallel workflows

Session resilience / แนวทางสำหรับผู้ปฏิบัติการ

Use Capture Incident in Control Center or Live Logs when a turn looks wrong. Validate the configured tunnel health endpoint against the live runtime address:

profile="$HOME/Library/Application Support/tunnel-client"
tc="${MOONLIGHT_TUNNEL_CLIENT_PATH:-/Applications/Moonlight.app/Contents/Resources/tunnel-client/tunnel-client}"
[ -f "$tc" ] || exit 1
"$tc" doctor --profile moonlight --profile-dir "$profile" --explain || exit 1
address=$(grep -E 'health.*(listening|listen_addr).*(127\.0\.0\.1|localhost):[0-9]+' "$profile/moonlight-tunnel.log" | tail -1 | grep -oE '(127\.0\.0\.1|localhost):[0-9]+' | tail -1)
[ -n "$address" ] || exit 1
curl "http://$address/healthz"

Security and operational model

Moonlight is powerful by design — use it only on machines and workspaces you trust.

• Active Project scope bounds mutations; the exact delete_file is the only mutation eligible for scoped auto-approval, and only when the target is proven recoverable inside the Active Project.

• Approval — with Full Bypass OFF, approval-required mutations need explicit chat confirmation plus an independent trusted host exact-action approval. Desktop dialogs are cancel-first; standalone/headless runtimes without a trusted host approval provider fail closed.

• Recovery Trash — deleted files and pre-replacement backups are recorded under <dataRoot>/recovery-trash (or encrypted checkpoints) before the authoritative mutation.

• Full Bypass — a separate opt-in control (default OFF) that skips application-level approval/scope checks for explicit targets; it cannot override OS permissions or input validation.

• Loopback MCP binds to 127.0.0.1; use the Secure MCP Tunnel for remote access. The tunnel profile stores only an env: key reference, never the key.

Build from source

Requirements: macOS, Node.js 24 (nvm/nodejs.org, not Homebrew), Corepack + pnpm 10.15.0.

git clone https://github.com/misternay/moonlight-mcp-plugin.git
cd moonlight-mcp-plugin
corepack pnpm@10.15.0 install --frozen-lockfile
corepack pnpm@10.15.0 build
corepack pnpm@10.15.0 desktop        # dev desktop app
corepack pnpm@10.15.0 package:macos  # DMG + ZIP (x64 + arm64)

Checks: lint, typecheck, test:release, docs:tools:check. Layout: apps/desktop (Electron), apps/cli, packages/*, docs/.

Tools

The complete generated tool index (228 total definitions; 192 advertised by default; 198 with Codex enabled) lives in docs/TOOL_CATALOG.md.

Docs

• Tools catalog (complete generated index)

• ภาษาไทย · Architecture · Release process · Contributing

License

This project is licensed under the MIT License.

Moonlight is a fork of lnwjud by Adisorn NM — original author credit goes to them and the original project, which this fork builds on.