# Camofox Opencli

> Cloud OpenCLI on Camofox anti-detection Firefox — 163+ site adapters in one Docker container. noVNC for QR login, cookies persist in volume. Exposes REST + MCP server (and a Claude skill) at :8080 for external agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-fectivnfy112357-camofox-opencli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Fectivnfy112357](https://agentstack.voostack.com/s/fectivnfy112357)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Fectivnfy112357](https://github.com/Fectivnfy112357)
- **Source:** https://github.com/Fectivnfy112357/camofox-opencli
- **Website:** https://github.com/Fectivnfy112357/camofox-opencli

## Install

```sh
agentstack add mcp-fectivnfy112357-camofox-opencli
```

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

## About

# Camofox · OpenCLI ☤

Camofox + OpenCLI — 163+ website adapters in the cloud. One Docker container combining [Camofox](https://github.com/jo-inc/camofox-browser) anti-detection browser + [Shim](https://github.com/Fectivnfy112357/camofox-shim) bridge layer.

[](LICENSE)
[](https://www.docker.com/)
[](https://nodejs.org/)
[](README.zh-CN.md)

## Cloud OpenCLI + VNC Remote Login

OpenCLI runs natively on your desktop — a Chrome browser on your laptop, a local daemon controlling it via Chrome Extension. It stops working the moment you close your laptop.

Camofox · OpenCLI moves it to the cloud:

```
Your computer            Cloud server
───────────              ─────────────
                           ┌──────────────────────────────┐
                           │   Docker container            │
                           │                              │
  opencli zhihu            │   OpenCLI Daemon             │
  search 'AI agent'  ─────▶   (:19825)                    │
                           │        │                     │
                           │        │ WebSocket           │
                           │        ▼                     │
                           │   Camofox Shim               │
                           │        │                     │
                           │        │ REST API            │
                           │        ▼                     │
                           │   Camofox Firefox browser    │
                           │   (:9377)                    │
                           │                              │
  Open noVNC link          │   VNC remote desktop (:6080) │
  in browser ─────────────▶  ← scan QR, cookies persist   │
                           │                              │
                           └──────────────────────────────┘
```

**Log in once, always online.** Open Zhihu/Xiaohongshu/Xianyu via noVNC, scan the QR code once, and the cookies are written to the Docker Volume. After that, every `opencli` command automatically carries the login session — even after container restarts or rebuilds.

**Zero changes to OpenCLI source.** All 163 adapters call `page.goto()`, `page.evaluate()`, and other browser APIs. The Shim impersonates a Chrome Extension, connects to the OpenCLI daemon's WebSocket, intercepts commands, translates them into Camofox REST API calls, and sends results back. OpenCLI has no idea the browser behind it is Firefox.

## How It Works

```
┌──────────────────────────────────────────────────────────────────┐
│                        Docker container                           │
│                                                                  │
│  User runs: opencli zhihu search 'AI agent'                      │
│         │                                                        │
│         │ HTTP POST /command                                     │
│         ▼                                                        │
│  ┌──────────────────────────────────┐                            │
│  │  OpenCLI Daemon (:19825)         │  ← unmodified daemon       │
│  │  HTTP Server + WebSocket /ext    │                            │
│  └──────────┬───────────────────────┘                            │
│             │ WebSocket forwards commands                        │
│             ▼                                                    │
│  ┌──────────────────────────────────┐                            │
│  │  Camofox Shim (v2)               │  ← bridge layer            │
│  │  • Impersonates Chrome Extension │                            │
│  │  • Connects to daemon /ext WS    │                            │
│  │  • Translates commands → REST    │                            │
│  └──────────┬───────────────────────┘                            │
│             │ HTTP REST                                          │
│             ▼                                                    │
│  ┌──────────────────────────────────┐                            │
│  │  Camofox browser (:9377)         │  ← Firefox engine          │
│  │  • Anti-detection fingerprinting │                            │
│  │  • VNC remote desktop (:6080)    │                            │
│  │  • Cookie persistence            │                            │
│  └──────────────────────────────────┘                            │
└──────────────────────────────────────────────────────────────────┘
```

### Command Translation: DaemonCommand → Camofox REST API

OpenCLI sends 14 `DaemonCommand` types over WebSocket. The Shim maps them to Camofox REST endpoints:

| OpenCLI Command | Purpose | → Camofox API | Status |
|----------------|------|---------------|:---:|
| `navigate` | Page navigation | `POST /tabs/:tabId/navigate` | ✅ |
| `exec` | JS evaluation | `POST /tabs/:tabId/evaluate` | ✅ |
| `screenshot` | Screenshot | `GET /tabs/:tabId/screenshot` | ✅ |
| `cookies` | Get cookies | `GET /sessions/:userId/cookies` | ✅ |
| `tabs` | Tab management | `POST/GET/DELETE /tabs` | ✅ |
| `insert-text` | Text input | `POST /tabs/:tabId/press` | ✅ |
| `bind` | Bind tab | Internal mapping | ✅ |
| `close-window` | Close window | `DELETE /sessions/:userId` | ✅ |
| `cdp` | Chrome DevTools | — | ❌ Firefox has no CDP |
| `set-file-input` | File upload | — | ❌ Not implemented |
| `network-capture-*` | Network capture | — | ❌ No Firefox equivalent |
| `wait-download` | Download wait | — | ❌ Not implemented |
| `frames` | Iframe list | — | ❌ Not implemented |

> 8/14 commands implemented, covering all core social platform adapter needs. Unimplemented CDP/network commands don't affect Bilibili, Zhihu, Xiaohongshu, Twitter, etc.

### A Complete Data Flow

```
1. User: opencli zhihu search 'AI agent'
2. CLI → HTTP POST /command → daemon(:19825)
3. Daemon → WebSocket /ext → Shim (impersonating Chrome Extension)
4. Shim parses: {action: "navigate", url: "https://www.zhihu.com/search?q=..."}
5. Shim → Camofox: POST /tabs/:tabId/navigate {userId, url}
6. Shim parses: {action: "exec", code: "wait for page load → scrape results"}
7. Shim → Camofox: POST /tabs/:tabId/evaluate {expression: code, timeout: 120000}
8. Camofox returns JSON → Shim → WebSocket → Daemon → CLI → user sees results
```

## MCP + Skill for External Agents

The container also runs an **opencli gateway** (`:8080`) that exposes all 163+ platform adapters to external agents through two transports, plus a ready-made Claude skill:

| Transport | Endpoint | Auth |
|---|---|---|
| REST | `GET/POST /health`, `/sites`, `/sites/:site/help`, `/run`, `/login` | `Authorization: Bearer $GATEWAY_API_KEY` |
| MCP | `POST /mcp` (streamable HTTP) | same Bearer token |

### Tools exposed via MCP

- **Generic**: `list_sites`, `site_help`, `run_command`, `browser`, `login`, `doctor`
- **Per-site** for 10 primary platforms (each description embeds its own command list): `xiaohongshu_command`, `bilibili_command`, `twitter_command`, `reddit_command`, `zhihu_command`, `douyin_command`, `weibo_command`, `youtube_command`, `hackernews_command`, `github_command`
- All other ~160 sites are reachable through `run_command` + `site_help`

### Connect an MCP client

Claude Desktop (`claude_desktop_config.json`) or Claude Code (`.mcp.json`):

```json
{
  "mcpServers": {
    "camofox-opencli": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer YOUR_GATEWAY_API_KEY" }
    }
  }
}
```

The `login` tool returns a noVNC URL — open it in your browser to scan a QR code and persist cookies for sites that need authentication.

### Drop-in Claude skill

`skills/opencli-camofox/` ships with the container — stdlib-only Python scripts calling the gateway over HTTP. Set `OPENCLI_GATEWAY_URL` + `GATEWAY_API_KEY` (or `~/.opencli-gateway.env`) and your Claude agent can `list_sites`, `site_help`, `run`, `browser`, and `vnc_login` with no extra setup.

### Gateway env

| Variable | Default |
|---|---|
| `GATEWAY_PORT` | `8080` |
| `GATEWAY_API_KEY` | _(required for auth on REST + MCP)_ |
| `OPENCLI_BIN` | `opencli` |
| `OPENCLI_MANIFEST` | `/opt/opencli/cli-manifest.json` |

## Quick Deploy

### Option A — Pre-built image (recommended)

A self-contained image is published to GitHub Container Registry on every
change to `main`. The build bakes in the Camoufox binary, uBlock Origin and
GeoLite2-City.mmdb, so you only need to pull — no network access, no build
context preparation.

```bash
docker pull ghcr.io/fectivnfy112357/camofox-opencli:latest
docker run -d --name camofox \
  --privileged --shm-size=2g \
  -p 9377:9377 -p 6080:6080 -p 19825:19825 -p 8080:8080 \
  -e CAMOFOX_USER_ID=yourname \
  -e GATEWAY_API_KEY=$(openssl rand -hex 32) \
  -e CAMOFOX_API_KEY=my_secret_api_key_123 \
  -v camofox_data:/home/node/.camofox \
  ghcr.io/fectivnfy112357/camofox-opencli:latest
```

Then open `http://localhost:6080` (noVNC) and log in to the sites you want
through a real browser. Cookies are persisted in `camofox_data` so subsequent
runs stay signed in.

### Option B — Build from source

Forks are checked in as git submodules, so a build needs your fork URLs in
`.gitmodules`. Run this in a clean checkout:

```bash
git clone --recurse-submodules https://github.com/Fectivnfy112357/camofox-opencli.git
cd camofox-opencli
docker compose build --no-cache
docker compose up -d
```

If you only want OpenCLI / Shim changes to hot-reload without rebuilding the
image, prefer `--no-build`:

```bash
./deploy.sh --no-build
```

## Usage

```bash
docker exec -it camofox bash

# No login required
opencli bilibili search 'gaming'
opencli v2ex hot

# Login required (see VNC login below)
opencli zhihu search 'AI agent'
opencli xiaohongshu search 'camping'

# List all 163 platforms
opencli list
```

## VNC Remote Login

For platforms requiring login (Zhihu, Xiaohongshu, Twitter, etc.), use noVNC to scan a QR code once — cookies persist automatically:

```bash
# Generate a VNC link and auto-navigate to the target site
python3 scripts/camofox-vnc-login.py fectivnfy --url https://www.zhihu.com

# Output: http://textvision.top:6080/vnc.html?autoconnect=true&resize=scale&token=xxxx
# Open in browser → scan QR → done
```

After logging in once, all `opencli` commands automatically reuse the session. Cookies are stored in a Docker Volume — they survive container restarts and rebuilds.

## Updating

```bash
cd camofox-opencli
git pull
git submodule update --init --remote
docker compose down && docker compose build --no-cache && docker compose up -d
```

> **Submodules stay fresh automatically.** `camofox-opencli/.github/workflows/bump-submodules.yml` runs on a daily cron (UTC 03:17) — every submodule pointer lands on upstream HEAD within 24h of a sub-repo push. **No secrets to configure**: the workflow uses the auto-injected `GITHUB_TOKEN`, which has `contents: write` + `pull-requests: write` on this repo via the workflow's `permissions:` block.
>
> For instant bumps (instead of waiting up to 24h), each sub-repo has a `.github/workflows/notify-aggregate.yml` that calls `repository_dispatch` on every push. Cross-repo dispatch needs a PAT, so that step is guarded and skipped silently if the sub-repo doesn't have `AGGREGATE_DISPATCH_TOKEN` set — the daily cron still catches everything.

## Subprojects

| Repository | Description | License |
|-----------|------|------|
| [camofox-browser](https://github.com/Fectivnfy112357/camofox-browser) | Camofox fork, added GET cookies endpoint | MIT |
| [camofox-shim](https://github.com/Fectivnfy112357/camofox-shim) | WebSocket bridge, OpenCLI ↔ Camofox | MIT |
| [OpenCLI](https://github.com/Fectivnfy112357/OpenCLI) | 163+ site adapters CLI tool | MIT |

## License

This project is licensed under the [MIT License](LICENSE).

Subproject licenses:
- **camofox-browser** — Based on [jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) (MIT), fork adds `GET /sessions/:userId/cookies` endpoint and `entrypoint-camofox.sh`.
- **camofox-shim** — Original project, MIT.
- **OpenCLI** — Based on [jackwener/OpenCLI](https://github.com/jackwener/OpenCLI) (MIT), fork is unmodified, used as a submodule.

All three subprojects retain their upstream MIT licenses. This project is also MIT.

---

Built with ❤️

## Source & license

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

- **Author:** [Fectivnfy112357](https://github.com/Fectivnfy112357)
- **Source:** [Fectivnfy112357/camofox-opencli](https://github.com/Fectivnfy112357/camofox-opencli)
- **License:** MIT
- **Homepage:** https://github.com/Fectivnfy112357/camofox-opencli

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-fectivnfy112357-camofox-opencli
- Seller: https://agentstack.voostack.com/s/fectivnfy112357
- 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%.