Skip to main content
Glama

ZeroIDE MCP

Let any AI agent control your Windows PC — from a chat in the browser, from another computer or from anywhere else — but only while you allow it.

v0.5.0 · Install · Connections · Security · Telegram @danywalery · Русская версия

ZeroIDE MCP is an MCP server with a Windows tray app. Any AI client that supports MCP (Claude, ChatGPT, Cursor, Codex, Notion and others) gets tools to run PowerShell commands and work with files on this PC. The server is off by default: you switch it on in the tray for as long as you need it, approve sensitive actions and see every call in the audit log.

Status: 0.5.0. Safer agent work: risk cards with a diff, self-protection and undo of agent changes in Settings → Changes. Manual installation with a step-by-step wizard, no agent needed. The automated suites pass in CI; the manual path was tested on a clean PC (install, ngrok) and on a development PC (Tailscale, uninstall). Not all AI clients have been tested. See Known limits.

Demo

See ZeroIDE MCP in action.

https://github.com/user-attachments/assets/525d61c6-c8bc-4902-a694-90eb2ba04891

Related MCP server: mcp-opentym

What it is for

  • Any agent, wherever it runs. A web chat in the browser (ChatGPT, Claude, Notion or another one with MCP support), a coding agent on this PC (Claude Code, Cursor, Codex) or an agent on another computer: each of them can control this PC with the same tools. The agent does not have to run on the PC it controls.

  • Several PCs from one place. Install ZeroIDE MCP on each computer and add each one to your AI client as a separate MCP server. One agent can then run a single task across several PCs at once: for example, build on one, test on another and collect the results on a third. An agent running on one of your PCs can control the others the same way.

  • Over your own private network. Computers in your Tailscale network (tailnet) reach each other without a public address, so an agent on one PC can lead a task on the others inside the tailnet. For a cloud AI there is a public HTTPS address through ngrok, Cloudflare Tunnel or your own server.

Each PC keeps its own approvals, tokens and audit log: a token for one PC does not work on another.

19 MCP tools: commands, files, screen, images, messages, PC info, records

Features

  • 19 MCP tools: PowerShell commands (including background jobs and their output), files (read, write, edit, list, search, copy, move, delete), images, system info, task status, messages to the owner with an Open button, screenshots, the audit log and an agent journal.

  • Off by default. The server listens on 127.0.0.1 only and runs only while it is switched on in the tray. Switching it off or exiting the tray closes access through the app.

  • Approvals. By default reading is allowed, while writing or editing files and running commands wait for your confirmation in the tray.

  • Risk cards. Every command and file change is rated low, medium, high or critical; the approval card explains the risk in plain words and shows the diff of a file change. A critical call defaults to Deny and can only be allowed once.

  • Undo of agent changes. Before an agent overwrites, edits or deletes a file, the previous version is kept in ZeroIDE history for 30 days. Settings → Changes (or Agent changes (undo)… in the tray menu) lists the changes with Undo and Compare.

  • Self-protection. Agents cannot read ZeroIDE's own tokens or change its settings, journals and history through MCP tools.

  • Access control. OAuth sign-in that you approve in the tray, or named tokens with a scope (read, read-write or full), an optional folder they cannot leave, an expiry date and a request limit. Tokens can be rotated and revoked.

  • Remote access of your choice. Local only, a private network such as Tailscale, ngrok, Cloudflare Tunnel with your own domain, or your own SSH server. Accounts and domains are yours; the project runs no gateway of its own. See CONNECTIONS.md.

  • Audit. Every tool call is logged, with secrets masked.

It is not a sandbox: allowed commands run with your Windows user's permissions. Treat every connection as remote code execution on the PC and read SECURITY.md.

Requirements

  • Windows 10 or 11, x64, PowerShell 5.1 or later. No administrator rights needed.

  • Internet during installation: portable Node.js is downloaded and checked against a pinned SHA-256.

  • An AI client with MCP support. Cloud and web clients need a reachable HTTPS address, for example through ngrok. An agent on another of your PCs can use a private network such as Tailscale instead.

Install

Watch a real setup and first task with Notion.

https://github.com/user-attachments/assets/d63313c4-a18b-4e34-800a-dda48920bb82

Prefer to do it by hand? Since 0.4.0 the setup wizard walks you through install and connection step by step, no agent needed.

https://github.com/user-attachments/assets/bf236d57-153f-4582-bf66-d85fc6aa6133

  1. Open the Releases page of this repository and download zeroide-mcp.zip (not the "Source code" archives). You can compare its hash with zeroide-mcp.zip.sha256:

    Get-FileHash .\zeroide-mcp.zip -Algorithm SHA256
  2. Extract the archive (it unpacks into a single zeroide-mcp folder) and start ZeroIDE-MCP.exe from that folder. The setup wizard opens: it explains what the app does and offers two ways in.

    • Manually, with guidance. The wizard installs everything, then asks which AI you want to connect (an agent on this PC, ChatGPT, Claude, Notion, another computer) and walks you through the connection. For a web chat it recommends ngrok and does the technical part; you only sign in to ngrok, paste the key into the app's window and approve the launch. For another computer of yours it sets up Tailscale (installs it if needed, waits for your sign-in, publishes the server inside your tailnet with Tailscale Serve). With your own domain it runs cloudflared for a Cloudflare Tunnel you create in Zero Trust. An address of your own goes in as "I already have an address".

    • With an AI agent on this PC. The wizard gives you a task to paste into Claude Code, Cursor, Codex or another agent; the agent follows AGENT_INSTALL.md from the archive. If you prefer the command line, the same installer runs with powershell -NoProfile -ExecutionPolicy Bypass -File .\installer\install.ps1 (add -Update to update an existing installation).

  3. Switch MCP on in the tray when the AI needs access. To remove everything later, use Uninstall in Settings: it stops connections, deletes the installation folder with all tokens and logs, the Start Menu shortcut and the autostart entry. The connection wizard is always available again under Connection; docs/AGENT_CONNECTIONS.md has the details for agents.

The installer puts everything in %LOCALAPPDATA%\ZeroIDE-MCP, never prints tokens and does not switch MCP on by itself. It uses the local ports 39011 and 39012. Windows SmartScreen may warn about an unsigned app on first start; the exe is the same one published in the release.

Repository layout

Path

Contents

server/

MCP server for Node.js (server.mjs) and the token CLI (tokens-cli.mjs)

tray/

Tray app (C#, .NET 8, Windows Forms): starts and stops the server and the connection, approvals, access, journal

installer/

install.ps1 for the release package

tools/

Connection and onboarding helpers used by the installer and by agents

tests/

Automated tests; they run isolated and never touch an installed copy

docs/

Agent connection guide, building from source, release notes

AGENT_INSTALL.md, agent-manifest.json

Entry point for an AI agent that installs from the release package

Building from source

The repository holds source only; releases are built by GitHub Actions. To build and test locally, see docs/BUILDING.md.

Known limits

  • The release package and the tray app are not code-signed yet, so Windows SmartScreen may warn.

  • The tray targets .NET 8, whose Microsoft support ends on 10 November 2026. A move to a newer .NET is planned.

  • Not yet fully tested: installation and onboarding across all scenarios and AI clients; recovery after a reboot or crash; public access through Cloudflare or Tailscale Funnel.

  • Tailscale has no built-in helper in the tray yet: an agent sets it up by hand using the general connection steps in docs/AGENT_CONNECTIONS.md. Access over a tailnet address was checked during development.

  • Request limits count per client address as the server sees it. Behind a tunnel all remote traffic shares one address.

License

MIT No Attribution (MIT-0). Third-party components keep their own licenses, see THIRD_PARTY_NOTICES.md.

Available Tools

19 tools
agent_messageAgent messengerA
Read-only

Send a live message/instruction to another working agent connected to this ZeroIDE MCP server (for example, when coordinating from another PC or another session), or list currently active agents and their tasks (action: 'list_agents'). When action: 'send' is used, if the target agent is currently executing run_command, its command is immediately backgrounded into a job_id (or stopped if stopCommand: true) and your message is delivered in <50ms; otherwise the target agent's very next tool call pauses at the gate with your message.

Inputs: to, from, note, text, +3 more.

audit_logAudit logA
Read-onlyIdempotent

Read the MCP audit trail: who (which session) ran which command or edited which file, when, and with what exit code. USE THIS FIRST when something broke, when a file looks unexpectedly changed, or when you suspect another agent worked in parallel. Filters: onlyErrors, tool, contains, sinceMinutes.

Inputs: note, tool, agent, limit, +3 more.

await_ownerStandby for owner (5 min)A
Read-onlyIdempotent

Call at the end of a completed task (right after task_status({ status: 'done' })) to hold the MCP connection open for 5 minutes (default waitMinutes: 5) so the PC owner can send you follow-up instructions from the ZeroIDE tray even if they do not have access to the chat window. Uses 45-second keepalive pulses under the hood so cloud proxies never time out. If it returns STANDBY_KEEPALIVE, immediately call await_owner({ agent, continueStandby: true }) until either the owner sends a message (NEW_INSTRUCTION_FROM_OWNER) or the 5 minutes expire (STANDBY_TIMEOUT_COMPLETED / STANDBY_RELEASED_BY_OWNER).

Inputs: note, agent, summary, waitMinutes, +1 more.

edit_fileEdit fileA
Destructive

Replace exact text fragments in a file instead of rewriting the whole file. One edit: oldString/newString. Several edits in one atomic change: edits=[{oldString,newString,replaceAll?}] — applied in order, all or nothing. Refuses an edit whose oldString is not found or found more than once (unless replaceAll), so it can never patch the wrong place. Supports expectedSha256 (safe concurrent editing) and dryRun preview; the previous version is kept in ZeroIDE history for undo. Write is atomic.

Inputs: path (required), note, agent, edits, +7 more.

file_opsFile operationsA
Destructive

Copy, move/rename or delete files and folders, or create a folder, without a shell. delete never destroys data: the files move to ZeroIDE history and the owner can restore them in Settings → Changes. Anything replaced with overwrite=true keeps its previous version too. Prefer this to Remove-Item/Move-Item in run_command: it is reversible and the owner sees exactly what changes.

Inputs: op (required), path (required), to, note, +3 more.

job_outputJob outputA
Read-onlyIdempotent

Fetch output of a background job, or of a finished run_command whose result was truncated (it reports a job_id). Supports paging through large output with offsetBytes/maxBytes, so nothing is lost even for very long build logs.

Inputs: jobId (required), note, agent, stream, +2 more.

job_statusJob statusA
Read-onlyIdempotent

Check the status of a background command started by run_command with wait=. Returns status (running/completed/timeout/failed), exit_code and duration. DO NOT poll in a tight loop. Pass waitSec (1-50): the server holds the answer until the job finishes or the time runs out, so one call replaces dozens. Pass tailLines to see the last lines of output and confirm real progress. Use job_output for the full log.

Inputs: jobId (required), note, agent, waitSec, +1 more.

journal_entryJournal entryA

Write to the agent journal the outcome of a finished chunk of work. summary — 2-4 sentences: what and why. outcome — done/failed/partial/reverted. next — what is left (optional). commit — git hash, if the work produced a commit (optional). refs — arbitrary references (optional). The server itself attaches all audit entries of the SAME session since the previous journal entry of that same session (or since the start of the connection, if there was no entry yet) — there is no need to find and specify the range manually. If you are explicitly continuing an interrupted task from another (older) session, pass continuesFromSeq — seq of the last accounted audit entry, so its tail is not lost.

Inputs: outcome (required), summary (required), next, note, +4 more.

journal_logJournal logA
Read-onlyIdempotent

Read the agent journal: what was done (summary), with what outcome (outcome), what is left (next), and which range of audit entries was attached automatically to each entry. Use at the start of work to quickly grasp recent context without reading the full audit_log.

Inputs: note, agent, limit, outcome, +2 more.

list_directoryList directoryA
Read-onlyIdempotent

List files and folders on this computer with size and mtime. Supports depth (recursive listing) and a result limit. Heavy folders (node_modules, .git, dist, build, ...) are skipped when recursing unless includeIgnored is true.

Inputs: note, path, agent, depth, +3 more.

read_fileRead fileA
Read-onlyIdempotent

Read a UTF-8 text file on this computer. Supports partial reads via startLine/endLine and a maxBytes cap (default 200 KB) so large files never flood the context. Returns size, total line count and sha256 (pass that sha256 back to write_file/edit_file as expectedSha256 for safe concurrent edits). Binary files are detected and refused.

Inputs: path (required), note, agent, endLine, +2 more.

read_imageView imageA
Read-onlyIdempotent

Look at an image file on this PC (PNG, JPEG, GIF, BMP, ICO, WebP): returns the picture itself, so you can check screenshots, UI renders, charts or photos the owner points you to. Large images are downscaled on the PC (maxSize, default 1600 px on the longer side; the file itself is not changed). Same folder rules as read_file; the owner may require approval because the picture leaves the PC.

Inputs: path (required), note, agent, format, +1 more.

run_commandRun commandA
Destructive

Run a bash command on this machine as the user who runs the server (that user's rights). Depending on the owner's permission settings a command may wait for approval in the tray or be refused. Default cwd is the project dir. Returns exit_code, status, duration_ms and separate stdout/stderr sections. Output is capped at maxOutputBytes (default 30 KB, head+tail kept, truncation is always reported; a truncated result includes a job_id, and job_output pages the full text). Set wait= to run long commands in background: you get a job_id immediately and poll it with job_status/job_output. Pass a unique requestId to make retries safe (a repeated requestId returns the cached result instead of running again).

Inputs: command (required), cwd, note, wait, +4 more.

search_filesSearch filesA
Read-onlyIdempotent

Search text in one file or across the files of a folder on this computer (path may point to either). Returns file:line matches with optional surrounding context. Heavy folders (node_modules, .git, dist, build, ...) are excluded by default, binary files are skipped. Use include ('*.ts') to narrow by file mask and regex=true for regular expressions. Always reports the true match count.

Inputs: query (required), note, path, agent, +6 more.

system_infoSystem infoA
Read-onlyIdempotent

One read-only call for the context you would otherwise gather with several commands: Windows version, CPU, memory, disks, displays, user, time zone, PowerShell and installed developer tools (node, npm, python, git, dotnet, java, go, rust, docker, winget). It also says how ZeroIDE is set up for you right now: project folder, folder confinement, your access scope, which tools run freely, ask the owner first or are disabled, active temporary grants and where undo history is kept. Call it once at the start of a task.

Inputs: note, agent, refresh.

take_screenshotScreenshotA
Read-onlyIdempotent

Capture the primary screen (1440px JPEG) and show it to the PC owner on a dedicated approval card with the exact preview image. The image leaves the PC ONLY if the owner approves (once or via a grant). Always asks unless an active grant exists. Pass a short "description" of why you need this screenshot: it is burned as a caption into the archived copy when the owner enabled screenshot archiving.

Inputs: note, agent, description.

task_statusTask statusA
Read-onlyIdempotent

MANDATORY on all multi-step tasks: register and update your current task in the tray (panel block + multi-agent tab + icon tooltip). Call within your first 2 tool calls with status: 'running', update every 3–5 calls so current, done and next always match reality, and when the task is complete MUST call with status: 'done' so the tray marks the task as completed (green check, stops progress animation) instead of leaving it looking like it is still running.

Inputs: title (required), done, next, note, +4 more.

user_messageAgent messageA
Read-onlyIdempotent

Show a short message to the PC owner in the tray (banner in the panel + icon tooltip; kind=request also pops a toast). PROACTIVELY call this to report key milestones, completion summaries, or questions/blockers — the PC owner watches the tray window directly. Display-only: nothing leaves the PC and nothing is executed. Pass open to hand over a result: the banner gets an Open button for that page, file or folder. Pass agent to identify yourself when multiple agents work in parallel. An empty text clears it.

Inputs: text (required), id, kind, note, +3 more.

write_fileWrite fileA
DestructiveIdempotent

Write a UTF-8 text file on this computer ATOMICALLY (temp file + rename, so a dropped connection never leaves a half-written file). Creates or overwrites the file. Pass expectedSha256 (from read_file) to refuse the write if the file changed meanwhile — this prevents silently overwriting work done by another agent in parallel. The previous version is kept in ZeroIDE history (not next to the file), so the owner can undo the change in Settings → Changes; backup=false skips that. Use dryRun=true to preview a diff without writing.

Inputs: path (required), content (required), note, agent, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 19 tools

    Disambiguation4/5

    Each tool targets a distinct resource+action: file ops (read/write/edit/list/search/ops), command execution (run_command/job_status/job_output), and observability (audit_log/journal_entry/journal_log) are cleanly separated. The only soft overlap is in the 'communicate with the human/agents' cluster — user_message vs task_status both render in the tray, and agent_message vs await_owner both concern messaging — but the descriptions make the boundaries clear.

    Naming Consistency4/5

    Everything is uniformly snake_case with no camelCase or casing drift, which is a strong baseline. However the style mixes verb_first action names (run_command, read_file, take_screenshot, list_directory) with noun_phrase resource names (task_status, agent_message, job_status, system_info, audit_log), so it misses a single predictable verb_noun pattern.

    Tool Count4/5

    19 tools is at the upper edge of the ideal range but each group earns its place: file CRUD, shell exec + background job management, human/agent messaging, and audit/journal observability. Nothing looks redundant or filler, though it is on the heavier side of well-scoped.

    Completeness4/5

    Coverage is unusually thorough for an agent control plane: full file lifecycle (read/write/edit/delete/list/search/image), command execution with background jobs and paged output, owner and agent messaging, and audit+journal history. Minor gaps remain (no dedicated job-cancel/kill tool — it is only reachable via agent_message stopCommand — and no first-class git operations), but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A lightweight MCP HTTP server giving AI assistants real tools to interact with your Windows machine, including running commands, file access, system info, web search, and browser automation.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A local, dependency-free MCP server that gives AI agents controlled access to the active Windows desktop, enabling automated interaction with applications through screenshots, clicks, typing, and window management.
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to securely control and interact with a local Windows machine through 218 configurable tools for files, Git, processes, Windows UI, browser automation, WSL, Office, recovery, skills, and child MCP servers.
      11 npm
      MIT