Provides a unified command interface for agents to search, run, and inspect websites, browsers, desktop applications, local tools, and MCP.
Also known as olo-dot-io/Uni-CLI, @zenalexa/unicli
- Stars
- 228
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- Apache-2.0
What is Uni-CLI MCP?
Uni-CLI provides a unified command interface for agents to search, run, and inspect websites, browsers, desktop applications, local tools, and MCP.
Summary generated from the project's README
About Uni-CLI MCP server
Uni-CLI provides a single command interface designed for AI agents to interact with a wide variety of digital environments. It allows agents to search, run, and inspect websites, web browsers, desktop applications, local tools, and MCP protocols. By installing the package via npm, developers can give their agents the ability to navigate complex interfaces ranging from structured APIs and local files to visual-only desktop software using accessibility trees or visual computer use.
The system operates by mapping user intent to specific candidate operations. It supports diverse execution methods such as the browser protocol for authenticated web sessions, semantic browser control for DOM interaction, and local runtimes for direct OS and process boundaries. This setup enables agents to receive structured data or actionable error messages when performing tasks. The runtime manages the interface while the developer maintains control over the model, planner, and sandbox environments.
What you can do with it
- 1Discover and rank web operationsAn agent can search for a specific task to find the most relevant available commands.
- 2Inspect browser delivery stateDevelopers can use the tool to check the health and status of the browser interface.
- 3Repair failed task pathsThe system can identify drift and provide commands to fix broken operation paths.
- 4Automate local tool executionAgents can interact with files and system state through a local runtime.
Written from the project's README. Every use case is checked against a quote from it.
How to install Uni-CLI MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Uni-CLI MCP in Claude Code
$ claude mcp add uni-cli -- npx -y @zenalexa/unicliInstall Uni-CLI MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"uni-cli": {
"command": "npx",
"args": [
"-y",
"@zenalexa/unicli"
]
}
}
}Install Uni-CLI MCP in VS Code
.vscode/mcp.json
{
"servers": {
"uni-cli": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@zenalexa/unicli"
]
}
}
}Install Uni-CLI MCP in VS Code CLI
$ code --add-mcp '{"name":"uni-cli","type":"stdio","command":"npx","args":["-y","@zenalexa/unicli"]}'Install Uni-CLI MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"uni-cli": {
"command": "npx",
"args": [
"-y",
"@zenalexa/unicli"
]
}
}
}Install Uni-CLI MCP in Codex
$ codex mcp add uni-cli -- npx -y @zenalexa/unicliInstall Uni-CLI MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.uni-cli] command = "npx" args = ["-y", "@zenalexa/unicli"]
Install Uni-CLI MCP in Gemini CLI
$ gemini mcp add -s user uni-cli npx -- -y @zenalexa/unicliInstall Uni-CLI MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"uni-cli": {
"command": "npx",
"args": [
"-y",
"@zenalexa/unicli"
]
}
}
}Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubUni-CLI gives people and agents one command interface for websites, browsers, desktop applications, local tools, and MCP. Describe a task, inspect the selected operation, and run it to receive structured data or an actionable error.
npm install -g @zenalexa/unicli
unicli search "list the top Hacker News stories"
unicli hackernews top --limit 3 -f json
Check releases or open an interactive Y/N update choice.
unicli upgrade --check -f json
unicli upgrade
Persistent non-interactive Agent installations update in a detached worker by default. Structured output reports progress through meta.update.automatic_update. Interactive terminals keep the Y/N choice, and unicli upgrade --no-auto-update switches a machine back to explicit approval.
Agent Internet Access
Find a source, search its records, and read native Markdown when the site provides it. Scholarly searches retain the requested source. HTTP responses carry retry and verification instructions. OpenRouter searches and paginates models on the server.
Read the access guide and reproducible benchmarks for behavior, measured gains, and source-side limits.
Route By Task
The catalog identifies available operations and their arguments. Execution uses the declared interface and limits the action to its target. Each call runs one provider; a failure retains its original cause and repair command.
| Task boundary | Execution operator | Why |
|---|---|---|
| Public data or stable service contract | Structured API | Typed fields, explicit auth, stable provenance |
| Files, system state, local tools | Local runtime | Direct process and OS boundaries without browser state |
| Authenticated or private web contract | Browser protocol | Explicit profile, cookie session, or network contract |
| Page-only web flow | Semantic browser | DOM and CDP semantics with an explicit target and session |
| Native desktop application | Accessibility | Structured AX, UIA, or AT-SPI control trees |
| Pixel-only or unstructured interface | Visual computer use | Coordinate and visual observation when no stronger interface exists |
unicli search "export my saved posts" # discover and rank
unicli list --site reddit # inspect one surface
unicli browser doctor --json # inspect browser delivery state
unicli repair reddit saved # verify a supported drift path
The Operation Contract
Each operation describes what it accepts, where it runs, and what it can change. Inspect that contract before sending arguments or granting approval.
intent → candidate operations → explicit selection → policy → substrate → receipt
| Stage | Runtime behavior |
|---|---|
| Discover | Compiled intent and bilingual retrieval return a small ranked set with selection evidence |
| Select | The caller chooses one operation with a declared strategy and substrate |
| Govern | open, confirm, and locked profiles evaluate effect and capability scope |
| Act | The selected adapter, core command, browser, desktop, or protocol path executes |
| Observe | Every normal command returns a stable success or error envelope |
| Repair | Owned drift paths expose their source, failed boundary, and bounded verification command |
| Evolve | Recorded failures become isolated candidates that must pass paired and held-out evaluation |
Uni-CLI supplies the interface runtime. The model, planner, agent loop, and sandbox remain independent choices.
Surfaces
| Surface | Current runtime |
|---|---|
| Web | Public data, cookies, headers, downloads, uploads, publishing, search, and Chinese platforms |
| Browser | CDP navigation, semantic action, network, snapshots, screenshots, and post-action evidence |
| Desktop | Native controls, macOS services, design tools, Office, and media applications |
| Local | Subprocess bridges, files, PDF and paper workflows, media transforms, and developer CLIs |
| Protocols | Native CLI, MCP stdio, MCP Streamable HTTP, ACP, generated configs, and agent skills |
| Policy | Permission profiles, deny rules, scoped approvals, recordings, replay, and evidence |
Static catalog
Fixed core and host-discovered commands join at runtime.
| Surface | Sites | Operations | Examples |
|---|---|---|---|
| social | 33 | 398 | twitter, zhihu, instagram, reddit |
| video | 8 | 76 | tiktok, youtube, bilibili, douyin |
| news | 11 | 45 | hackernews, bloomberg, bbc, 36kr |
| finance | 10 | 67 | eastmoney, xueqiu, binance, coingecko |
| shopping | 13 | 47 | amazon, jd, taobao, 1688 |
| dev | 37 | 185 | codex, cursor, gh, stackoverflow |
| ai | 25 | 216 | chatgpt, antigravity, chatwise, notebooklm |
| scholarly | 30 | 105 | openreview, zotero, pubmed, arxiv |
| patent | 17 | 42 | epo, espacenet, cipo, cnipa |
| reference | 12 | 47 | marxists-cn, anilist, bangumi, imdb |
| audio | 4 | 46 | spotify, netease-music, xiaoyuzhou, apple-podcasts |
| content | 16 | 90 | lesswrong, danbooru, dlsite, weread |
| productivity | 10 | 78 | notion-app, ones, obsidian, quark |
| jobs | 6 | 42 | nowcoder, boss, 51job, linkedin |
| desktop | 25 | 201 | macos, freecad, blender, gimp |
| games | 1 | 7 | steam |
| utility | 7 | 29 | linear, bitwarden, todoist, qweather |
| other | 72 | 124 | slay-the-spire-ii, xiaoe, archive, ke |
| travel | 1 | 4 | ctrip |
The generated operation catalog is the authoritative inventory.
Use It From An Agent
Native CLI
unicli search "download the latest arXiv paper on computer use" -f json
unicli arxiv search "computer use agents" --limit 5 -f json
unicli --auth-retry openreview conference "ICML.cc/2026/Conference" --rpm 20 -f json
unicli extract https://example.com --max-chars 1200
Piped output defaults to Markdown. Use -f json, yaml, csv, or compact when the next step needs a stable machine format. The OpenReview archive guide covers authenticated, resumable conference and multi-year research archives.
MCP
{
"mcpServers": {
"unicli": {
"command": "npx",
"args": ["-y", "@zenalexa/unicli-mcp"]
}
}
}
Equivalent command
npx -y @zenalexa/unicli mcp serve
The default profile exposes four meta-tools. Deferred and expanded profiles project adapter operations when the host needs tool-level discovery. Inspect the live projection with unicli mcp health -f json.
Local Computer
unicli compute apps --format compact
unicli compute snapshot --app Calculator --format compact
unicli compute find --app Calculator --role AXButton --title "7"
unicli compute click --ref <ref-from-find>
Desktop actions prefer accessibility references. Visual routes require an explicitly selected backend and never appear as a hidden fallback.
Results That Explain Themselves
Success
ok: true
schema_version: "2"
command: "hackernews.top"
meta:
duration_ms: 412
count: 3
surface: web
data:
- { rank: "1", title: "...", url: "...", author: "..." }
error: null
Failure
ok: false
schema_version: "2"
command: "reddit.saved"
data: null
error:
code: auth_required
adapter_path: "src/adapters/reddit/saved.yaml"
step: 1
suggestion: "Run: unicli auth setup reddit"
retryable: false
Exit codes distinguish success, empty results, unavailable dependencies, temporary failures, auth, and configuration. See the output and exit-code reference.
Repair Drift At The Owned Boundary
Use the source path in an adapter error to inspect the failed operation. A local adapter can replace the packaged version during repair development.
run → read error.adapter_path → patch the owned step → save override → verify once
unicli repair <site> <command>
repair does not edit source or Git state. It reruns the original command as a bounded subprocess and succeeds only when the target returns ok: true with exit code 0. Local overrides under ~/.unicli/adapters/ survive npm updates.
For repeated failures, evolve adapter keeps proposal evidence, validation, and held-out cases separate. The agent supplies one isolated YAML candidate and a falsifiable prediction. Uni-CLI runs paired baseline and candidate evaluations, records prediction misses and regressions, and installs a user override only after the promotion gate passes.
unicli evolve adapter <site> <command> \
--run <proposal-run> \
--candidate <candidate.yaml> \
--hypothesis "<expected mechanism>" \
--expect <validation-case-id> \
--risk <held-out-case-id> \
--validation <validation-eval.yaml> \
--held-out <held-out-eval.yaml> \
--promote
Without --candidate, the command creates an editable draft. Every verification preserves its candidate snapshot, patch, and report as one hash-checked attempt. evolve verify --promote reuses the latest eligible attempt when the candidate is unchanged. Promotion and rollback recover after an interrupted write and serialize competing Agent processes. evolve inspect returns the complete attempt history, reports corrupt sessions, and evolve rollback restores the exact pre-promotion overlay.
The first evolution scope keeps the operation identity, input and output contracts, pipeline action topology, request methods and headers, and existing subprocess invocations fixed. Same-origin endpoint and extraction repairs remain editable. A replacement network origin requires an explicit --allow-origin <origin> declaration when the session is created.
A minimal YAML adapter follows.
site: example
name: search
description: Search example.com
transport: http
strategy: public
pipeline:
- fetch: { url: "https://api.example.com/search?q=${{ args.query }}" }
- select: data.results
- map: { title: "${{ item.title }}", url: "${{ item.url }}" }
- limit: "${{ args.limit }}"
args:
- { name: query, type: string, required: true, positional: true }
- { name: limit, type: int, default: 20 }
columns: [title, url]
Read the adapter format, pipeline reference, and self-repair guide.
Trust Boundaries
- Live browser cookies remain in process memory unless the user explicitly runs
auth importorbrowser cookies. - Browser automation uses Uni-CLI-owned profiles under
~/.unicli/. Chrome 136+ does not support remote debugging on its default user-data directory. unicli browser doctor --jsonreports the available delivery path and exact repair command without starting a browser provider.- Permission rules authorize before browser, file, clipboard, subprocess, or desktop side effects. Explicit malformed policies fail closed.
- Visual routes require a real configured backend. Missing providers return a structured error.
- Invocation diagnostics exclude arguments, content, URLs, credentials, and raw errors; users can disable new events with
UNICLI_NO_LOG=1.
Credential selection, storage paths, and recovery are explained in Authentication. Browser visibility and desktop control are covered in Browser and Desktop.
Development
npm install
npm run typecheck
npm run lint
npm test
npm run verify # full E2E and adapter coverage; required before release
Requires Node.js 22.19 or newer. See CONTRIBUTING.md for adapter and engine conventions.
Browse every published version on the generated release history. The same data is available to Agents through docs/public/release-history.json.
License
Apache-2.0
Uni-CLI MCP questions
How do I add Uni-CLI MCP to Claude Code?
Run claude mcp add uni-cli -- npx -y @zenalexa/unicli in your terminal. Add --scope user to make it available in every project.
How do I add Uni-CLI MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I install Uni-CLI?
You can install it globally using npm with the command npm install -g @zenalexa/unicli.
How does Uni-CLI handle updates for agents?
Non-interactive agent installations update in a detached worker by default, while interactive terminals allow for manual Y/N choices.
Does Uni-CLI support desktop applications?
Yes, it provides access to native desktop applications through accessibility controls like AX, UIA, or AT-SPI.