nuphus-mcp: a stdio MCP server that gives any AI agent desktop and Chrome control

The gap nuphus-mcp fills between an LLM and the machine it runs on

An MCP client can call tools, but the tools it ships with usually stop at files, shell and HTTP. Nothing in that set clicks a button in a native window, drags a file, or reads a dialog that only exists as pixels. nuphus-mcp is a single stdio MCP server that exposes desktop and browser automation as standard MCP tools, so the client does not need a plugin per capability. The README describes the target audience directly: Claude Desktop, Cursor, VS Code, Copilot, or any MCP client. It is also the automation layer behind the Nuphus desktop app, which the README says uses the same vision-to-perceive flow. The project is explicit that it is not a DSH plugin. Users of DeepSeek Harness are told to install dsh-nuphus-mcp instead, which is a useful boundary to read before you spend an afternoon wiring the wrong package.

One binary, JSON-RPC over stdio, two Rust crates underneath

The architecture is deliberately small. The README's diagram shows an MCP client exchanging single-line JSON with the server over stdio; there is no HTTP listener, no daemon, and no port to open. Inside the workspace, the server crate sits on top of two others: desktop-api handles screen, window, mouse and keyboard, and nuphus-browser handles Chrome through the Chrome DevTools Protocol via chromiumoxide. The README notes desktop-api is built on xcap plus Win32 and carries no Tauri dependency, which matters if you want to embed the crate rather than run the binary. Tool count is 38, split into 15 desktop and 23 browser tools, with the full reference in TOOLS.md. The browser side is not just clicking coordinates: browser_snapshot returns an accessibility tree with @N refs, so an agent can address elements by reference instead of guessing pixel offsets. That is the difference between a script that breaks on every layout change and one that survives a restyle.

Installing nuphus-mcp and running a first screenshot

The README lists a stable Rust toolchain as the prerequisite and says to build from source with Cargo. The workspace Cargo.toml lists three members, so a build from the repository root compiles the server plus both cores. The only build command the repository states is cargo build, used from the workspace root:

cargo build

The README also points at an npm package, @nuphus/nuphus-mcp, for users who would rather not build. Either way you end up with a process that reads single-line JSON from stdin and writes responses to stdout. The README does not print a client configuration block, so take the binary path from your own build output rather than copying one from a blog post. The first tool worth calling is a desktop screenshot, which the README says returns PNG or base64. On macOS, expect desktop input to fail until you grant Accessibility permission under System Settings, Privacy and Security. On Linux, expect window and input tools to be partial.

Local OCR plus a vision model you supply, and why both exist

The vision story is the most interesting design decision here. There are two tools. desktop_vision sends a screenshot to your own vision model, configured through NUPHUS_MCP_VISION_API_KEY, NUPHUS_MCP_VISION_BASE_URL, NUPHUS_MCP_VISION_MODEL and NUPHUS_MCP_VISION_PROVIDER. The README's variable table gives the default base URL as https://api.openai.com/v1, and says pointing it at https://api.anthropic.com/v1 switches to the Anthropic native Messages API, either by host detection or by setting NUPHUS_MCP_VISION_PROVIDER=anthropic. desktop_perceive runs local OCR with PaddleOCR, with models auto-downloaded on first run, and optionally YOLO icon detection. The README's argument is that semantic understanding and pixel-precise coordinates are different jobs, and a vision model is good at the first while OCR and detection are good at the second. That is a fair split. The trade-off is operational: your first desktop_perceive call needs network access to fetch PaddleOCR models, so an air-gapped machine will fail there even though the rest of the server is local. Nothing is required unless you call desktop_vision, and the README says an unconfigured call returns a clear error rather than failing silently.

Where nuphus-mcp is the wrong tool

Platform support is uneven and the README does not hide it. Browser tools are full on Windows, macOS and Linux. Desktop tools are full only on Windows, because they go through the Win32 API. On macOS they work but desktop input requires Accessibility permission. On Linux the table says window and input capabilities are limited, which is a polite way of saying a Linux-only agent deployment will not get the same toolset. If your fleet is Linux containers, this server is the wrong layer; a headless browser driver will do more of what you actually need. There is a second boundary: the README states the project is not a DSH plugin, so DeepSeek Harness users installing nuphus-mcp directly are on an unsupported path and should use dsh-nuphus-mcp. Third, an agent driving a real mouse and keyboard is inherently fragile. Window focus, modal dialogs and timing are not abstractions the protocol hides, and no amount of tool annotation removes that. The README mentions destructive tools are annotated per the MCP spec and that strict-confirm mode exists, but annotations are advisory metadata for the client; they do not stop a misconfigured agent from clicking something irreversible.

How this differs from Playwright-style browser drivers

Playwright and Selenium drive a browser through a driver protocol and are built around test assertions, fixtures and a scripting language. They are excellent when the target is a web page and the machine is disposable. nuphus-mcp starts from the opposite assumption: the agent is already running, the target is whatever is on screen, and the browser is one surface among several. Its browser tools speak CDP directly through chromiumoxide, and its desktop tools go through xcap and Win32, so a single session can screenshot a native window, click a coordinate, then switch to a Chrome tab and address an element by its accessibility ref. The cost of that breadth is depth. A Playwright user gets auto-waiting, tracing and a mature selector engine; nuphus-mcp gives you browser_wait_for and an accessibility tree, and the rest is the agent's problem. If every task you have is a web form, Playwright is less work. If the task crosses between a desktop app and a browser, this is the layer that exists.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-08-30, which is recent enough to treat the project as moving. The release history shows v0.2.0, v0.2.1 and v0.2.2 all landing within roughly two days in late August 2026, so the version line is young and patch releases are still arriving quickly. That cuts both ways: fixes come fast, and the surface is still settling. The workspace Cargo.toml declares MIT at the workspace level, and the repository carries a LICENSE file plus a SECURITY.md and CONTRIBUTING.md. MIT is permissive, which means embedding the crates in a commercial product is not blocked by the licence itself, but the vendored desktop-api crate and the transitive dependencies each carry their own terms, and the README does not enumerate them. That is a review task for your legal team, not something to infer from the workspace field. Upgrade cost is dominated by two things: the pinned Cargo.lock, which you should diff on every bump, and the Chrome version your chromiumoxide build expects, since CDP is not a frozen interface. The README does not document rollback, so keep the previous binary.

Editorial conclusion

Adopt nuphus-mcp if you are building an MCP client that needs screen, window, input and Chrome control, and your agents run on Windows or macOS with Accessibility granted. Skip it if you need Linux desktop parity, or if your client is DeepSeek Harness, where dsh-nuphus-mcp is the intended install. Verify first that your MCP client speaks stdio JSON-RPC, that Chrome or Edge is on the machine, and that you have a vision model endpoint ready if you plan to call desktop_vision.

Frequently asked questions

Official sources

1. License: MIT
2. mrpulor-gh/nuphus-mcp on GitHub
3. Project website
4. README
5. Releases