by mrpulor-gh
Desktop automation MCP server — computer use for any AI agent: control screen, windows, mouse/keyboard, and Chrome via Model Context Protocol (stdio)
# Add to your Claude Code skills
git clone https://github.com/mrpulor-gh/nuphus-mcpLast scanned: 8/4/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-08-04T06:28:53.556Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}nuphus-mcp is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by mrpulor-gh. Desktop automation MCP server — computer use for any AI agent: control screen, windows, mouse/keyboard, and Chrome via Model Context Protocol (stdio). It has 221 GitHub stars.
Yes. nuphus-mcp passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/mrpulor-gh/nuphus-mcp" and add it to your Claude Code skills directory (see the Installation section above).
nuphus-mcp is primarily written in Rust. It is open-source under mrpulor-gh on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh nuphus-mcp against similar tools.
No comments yet. Be the first to share your thoughts!
Desktop automation MCP server — computer use for any AI agent. See the screen, control windows/mouse/keyboard, and drive Chrome over the Model Context Protocol (stdio). Desktop & browser automation need no API key; OCR runs locally; vision plugs into your own vision LLM (OpenAI-compatible or Anthropic native, BYOK).
nuphus-mcp is a lightweight, cross-platform desktop automation MCP server
that exposes desktop + browser automation as standard MCP tools. It speaks
JSON-RPC 2.0 over stdio — no daemon, no network service, one binary. Claude
Desktop, Cursor, VS Code, Copilot, or any MCP client can connect and
immediately control the screen, windows, keyboard/mouse, and Chrome —
computer use for any AI agent — desktop & browser automation need no API
key; local OCR is built in; vision works with your own vision LLM
(OpenAI-compatible, BYOK).
🇨🇳 Mainland China mirror: this repo is mirrored on Gitee for fast in-China access (Chinese docs served by default there). 中文文档
┌──────────────────┐ stdio JSON-RPC ┌──────────────────────┐
│ Any MCP Client │ ───────────────► │ nuphus-mcp │
│ (Claude/Cursor/ │ ◄─────────────── │ desktop-api crate │──► screen/window/mouse/keyboard
│ Nuphus itself) │ single-line JSON │ nuphus-browser crate│──► Chrome (CDP)
└──────────────────┘ └──────────────────────┘
desktop-api crate (xcap + Win32, no Tauri dependency).desktop_vision (BYOK — send a screenshot to your
own vision model via an OpenAI-compatible or Anthropic native API) +
desktop_perceive (local OCR with PaddleOCR, models auto-downloaded on first
run; optional YOLO icon detection). Used together they give AI agents both
semantic understanding
and pixel-precise coordinates — the battle-tested vision→perceive flow from
the Nuphus desktop app. See TOOLS.md for BYOK env vars, model
setup, and the recommended flow.@N
refs), click, type, exec, scroll, extract, screenshot, evaluate,
back/forward, wait_for, cookies get/set/import, upload, tabs, downloads —
implemented on nuphus-browser (chromiumoxide CDP).nuphus-mcp/
├── Cargo.toml # workspace root
├── TOOLS.md / TOOLS.zh-CN.md # 38-tool reference
├── crates/
│ ├── nuphus-mcp/ # MCP Server (this repo's product)
│ ├── nuphus-browser/ # Browser automation core (CDP)
│ └── desktop-api/ # Desktop control core (vendored)
└── ...
browser_* tools return a clear error.| Platform | Browser tools | Desktop tools |
|---|---|---|
| Windows | Full | Full (Win32 API) |
| macOS | Full | Desktop input requires Accessibility permission (System Settings → Privacy & Security → Accessibility) |
| Linux | Available | Partial — window/input capabilities are limited |
desktop_vision uses your own vision model. It speaks two protocols:
NUPHUS_MCP_VISION_BASE_URL at
https://api.anthropic.com/v1 and the protocol is auto-detected from the host;
or force it with NUPHUS_MCP_VISION_PROVIDER=anthropic.Nothing is required unless you call this tool — and when it is not configured the tool returns a clear error instead of silently failing.
| Environment variable | Required | Default | Description |
|---|---|---|---|
NUPHUS_MCP_VISION_API_KEY |
✅ | — | API key for your vision model |
NUPHUS_MCP_VISION_BASE_URL |
— | https://api.openai.com/v1 |
Base URL (https://api.anthropic.com/v1 for Claude) |
NUPHUS_MCP_VISION_MODEL |
✅ | — | Model id, e.g. gpt-4o-mini, qwen-vl-max, claude-sonnet-4-5 |
NUPHUS_MCP_VISION_PROVIDER |
— | auto |
auto | openai | anthropic; auto infers from the base URL host |
NUPHUS_MCP_VISION_MAX_TOKENS |
— | 1024 |
Max output tokens (Zhipu GLM-4V-Flash caps at 1024; raise for text-heavy screenshots) |
By default browser_* tools launch and manage their own Chrome instance. To
drive an external browser instead — e.g. an anti-detect / fingerprint
browser — start it with a debugging port and point the server at it:
| Environment variable | Required | Default | Description |
|---|---|---|---|
NUPHUS_MCP_BROWSER_CDP_URL |
— | — | External CDP endpoint, e.g. http://127.0.0.1:9222 |
# Example: start your fingerprint browser with a debugging port
chrome --remote-debugging-port=9222 --user-data-dir=...
// MCP client config
"env": { "NUPHUS_MCP_BROWSER_CDP_URL": "http://127.0.0.1:9222" }
When set, browser_* tools attach to that endpoint and never launch a managed
Chrome; attach failures are hard errors (no silent fallback into the wrong
browser). The external browser belongs to you — the server never kills it on
exit.
Fingerprint browsers typically get a new random debug port every time a
window is reopened, which would leave a fixed ..._CDP_URL pointing at a
dead port. Provide the browser identity and the server re-resolves the live
port automatically on the next tool call:
| Environment variable | Required | Default | Description |
|---|---|---|---|
NUPHUS_BROWSER_EXE_PATH |
for self-healing | — | Absolute path to the browser exe — the identity key used to locate the running window process |
NUPHUS_BROWSER_NAME |
— | 指纹浏览器 |
Display name used in error guidance |
NUPHUS_BROWSER_USER_DATA_DIR |
— | — | Profile dir, used to read DevToolsActivePort when the window was started with a random port (--remote-debugging-port=0) and the process cmdline does not reveal it |
// MCP client config — attach + self-heal
"env": {
"NUPHUS_MCP_BROWSER_CDP_URL": "http://127.0.0.1:9222",
"NUPHUS_BROWSER_EXE_PATH": "C:\\path\\to\\fingerprint-browser.exe",
"NUPHUS_BROWSER_NAME": "AdsPower",
"NUPHUS_BROWSER_USER_DATA_DIR": "C:\\path\\to\\profile"
}
With the identity set, if the configured endpoint stops answering the server
locates the window process by exe path, re-resolves its actual port (literal
cmdline port, or DevToolsActivePort in the profile dir for random-port
launches), verifies the candidate with a proxy-bypassing CDP probe and retries
once — close and reopen the window and the next tool call just works. Without
an identity, attach failures stay hard errors asking you to update the
configured URL. Either way there is no fallback to a managed Chrome.
desktop_perceive runs PaddleOCR and YOLO icon detection locally with ONNX
Runtime. The first call downloads the OCR models and icon_detect.onnx together
automatically into %APPDATA%\Nuphus\models (or NUPHUS_MODELS_DIR). Download
failures return a clear error with manual instructions. YOLO is optional at
runtime: if its download fails, perceive still returns OCR elements and reports
yolo_available: false (use NUPHUS_MCP_YOLO_MODEL_URL for a custom source).
See TOOLS.md → Vision & Local Models.
All other tools need no API key.
Install via npm (recommended — all platforms, prebuilt binaries):
npm install -g @nuphus/nuphus-mcp
The nuphus-mcp meta package installs the prebuilt binary for your platform
automatically (Windows x64/arm64, macOS arm64, Linux x64/arm64) and puts the
nuphus-mcp command on your PATH. No Rust toolchain needed:
nuphus-mcp # stdio MCP server
Build from source (requires the Rust toolchain):
cargo build --release -p nuphus-mcp
# binary at target/release/nuphus-mcp(.exe)
The server reads newline-delimited JSON from stdin and writes JSON-RPC responses to stdout. Logs go to stderr.
# quick smoke test
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test"}}}' | nuphus-mcp
This server can physically control the machine it runs on. By default write
tools run without confirmation; we strongly recommend enabling strict
confirmation so destructive operations require an explicit "confirm": true
argument from the client (otherwise the tool is rejected with isError).
Any one of the following:
# CLI flag
nuphus-mcp --confirm-write
# Environment variable (recommended — survive