# Cicy Desktop

> Electron desktop automation worker — 100+ system tools (Chrome/CDP, JS exec, screenshots, file/shell ops) over MCP & HTTP, with a homepage UI for managing local & remote AI teams.

- **Type:** MCP server
- **Install:** `agentstack add mcp-cicy-ai-cicy-desktop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cicy-ai](https://agentstack.voostack.com/s/cicy-ai)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [cicy-ai](https://github.com/cicy-ai)
- **Source:** https://github.com/cicy-ai/cicy-desktop
- **Website:** https://cicy-ai.com

## Install

```sh
agentstack add mcp-cicy-ai-cicy-desktop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CiCy Desktop

CiCy Desktop is an Electron-based desktop automation worker with a small cluster
control plane. It exposes ~100+ system tools — Chrome/CDP control, in-page
JavaScript, screenshots, clipboard, file ops, shell/node/python exec, system
info — over MCP and HTTP, plus a homepage UI for managing local and remote
teams. The `cicy-code` sidecar daemon is acquired at runtime (`npx cicy-code` on
mac/linux, Docker-in-WSL on Windows), not bundled.

## Screenshots

The homepage — your teams (the local sidecar, private-cloud teams, and custom
remote nodes), each a card you open as a tab:

A team opened as a tab — the agent roster on the left, a live conversation on
the right:

## CLI — `cicy-desktop`

`cicy-desktop` launches the Electron app — `npm start` and `npx cicy-desktop` run
the same entrypoint. Self-update with `cicy-desktop --update`; `--version` and
`--help` print info.

## Run (end users, no clone)

First run launches the Electron app and drops a desktop shortcut (Windows
`.lnk` / macOS `.app` / Linux `.desktop`, all with the CiCy icon); double-click
it afterwards.

**CN needs the electron mirror.** A fresh machine has no cached electron binary,
so electron's postinstall would otherwise hit GitHub releases and fail — point
`ELECTRON_MIRROR` and the npm registry at npmmirror.

### Windows — global install (not npx)

npx's libnpmexec lock false-positives as "Lock compromised" on Windows boxes
with realtime antivirus (Defender touches `node_modules` mtimes mid-install).
`npm i -g` has no such lock:

```cmd
cmd /c "set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/&& npm i -g cicy-desktop --registry=https://registry.npmmirror.com&& cicy-desktop"
```

Re-run the same line to update.

### macOS / Linux — npx

```bash
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm_config_registry=https://registry.npmmirror.com npx -y cicy-desktop
```

Outside CN (or once electron is cached) a plain `npx -y cicy-desktop` is enough.

## Develop

```bash
git clone git@github.com:cicy-ai/cicy-desktop.git
cd cicy-desktop
npm install
npm start
```

Config lives in `~/cicy-ai/global.json` (API token, gateway key, node list). The
worker reads its `Authorization: Bearer ` from there.

### Homepage UI (`workers/render`)

The desktop homepage — team cards, tabs, everything the user sees — is a Vite +
React app in `workers/render/`. The Electron main process loads a **prebuilt
snapshot** from `src/backends/homepage-react/` (a `file://` SPA: works offline,
no mixed-content issues embedding the team webview). Source and snapshot are two
different things — `scripts/build-homepage.cjs` (run on every `build:*` /
publish) rebuilds the snapshot so it never lags behind `workers/render/`.

Build → ship the snapshot:

```bash
cd workers/render && npm run build
rsync -av --delete dist/ ../../src/backends/homepage-react/
```

Fast dev loop (React/CSS HMR, no Electron restart): run Vite and source-mode
Electron with `CICY_HOMEPAGE_URL=http://localhost:8173` set (via `.env.dev`).
`src/backends/homepage-window.js` falls back to the bundled `file://` SPA if that
URL is unreachable, so the window never stays blank. Full platform/loop details
(Mac fast loop, Windows packaged, the three reload classes) are in the worker's
`CLAUDE.md`.

## Calling tools

The worker dispatches its tools three ways:

- **In-page (IPC):** `window.electronRPC(toolName, args)` — the bridge injected
  into trusted BrowserWindows.
- **HTTP (REST):** `POST /rpc/:toolName` with `Authorization: Bearer ` —
  served by the master, which forwards to the selected worker. `401
  Unauthorized` means the token is wrong or missing.
- **From an agent:** the `agent-desktop` / `agent-electron` / `agent-chrome`
  skills drive a connected client over WebSocket
  (`agent-desktop rpc `, `agent-desktop exec …`, etc.).

Discover tools at runtime:

- `list_tools` meta-tool (`electronRPC("list_tools")` / `agent-desktop rpc list_tools`)
- `GET /openapi.json` (browsable at `/docs`)

The worker exposes automation for: browser window lifecycle and navigation, CDP
page interaction, in-page JavaScript, screenshots / downloads / clipboard,
system window control and system info, and worker/master cluster coordination.

## Architecture

- worker/server entry — `src/main.js`
- desktop lifecycle CLI — `bin/cicy-desktop`
- tool implementations — `src/tools/*`
- master (routes `POST /rpc/:toolName` to workers) — `src/master/master-routes.js`
- homepage source — `workers/render/` → built into `src/backends/homepage-react/`

The **worker** dispatches tools in-process via `ipcMain.handle("rpc", …)` (what
`window.electronRPC` rides) and over HTTP; the live tool index is
`GET /openapi.json`. The desktop CLI starts a local master + worker cluster and
manages status/logs.

## License

[Apache-2.0](./LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cicy-ai](https://github.com/cicy-ai)
- **Source:** [cicy-ai/cicy-desktop](https://github.com/cicy-ai/cicy-desktop)
- **License:** Apache-2.0
- **Homepage:** https://cicy-ai.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cicy-ai-cicy-desktop
- Seller: https://agentstack.voostack.com/s/cicy-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.