A
licenseNot graded
qualityA
maintenanceA lightweight server that enables AI agents to interact with the Windows operating system, allowing for file navigation, application control, UI interaction, and QA testing through various tools.
9,079
MIT
winadmin-mcp
by prinzalx
It's a Windows-admin MCP server that exposes sharply typed tools for administering Windows — services, event logs, processes, network, scheduled tasks, registry, security and monitoring — each individually switchable, with least-privilege defaults and an approval gate.
Governance (currently enabled in the schema):
list_pendinglists destructive actions awaiting approval;confirm_actionexecutes a parked action by itsconfirmation_id.Services: inspect/control Windows services, including
diagnose_servicefor root-cause checks.Events:
query_events,explain_event_id(e.g. Kernel-Power 41, EventLog 6008),system_healthfor the last boot.Processes, Network, Scheduled Tasks, Registry, Security, Monitoring: query and act on each via their own tool groups.
Learnings: store and quote team learnings (e.g. a harmless DCOM entry) for later diagnosis.
Per-tool switching: a web dashboard at
http://127.0.0.1:8787turns each of the 46 switchable tools on/off; disabled tools disappear fromtools/listat runtime and become uncallable.Least privilege by default: on a fresh machine every tool is off, leaving only the two governance tools until a human enables more.
Approval gate: gated calls first request approval in the agent's own MCP elicitation popup, otherwise they park in the dashboard; by default an agent cannot confirm its own parked action.
Interface: MCP over stdio (Node ≥20), 48 tools total in
tools/list(46 switchable + 2 governance), MIT licensed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@winadmin-mcpshow me all Windows services that are stopped but set to start automatically"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
winadmin-mcp
A Windows-admin MCP server for agents (Claude Code, Codex, Hermes, …): services, event logs, processes, network, scheduled tasks, registry, security and monitoring through sharply typed tools — without the agent having to build PowerShell quotes itself.
Plus a web dashboard (http://127.0.0.1:8787), in which every tool can be switched on and
off individually. What is off disappears from tools/list at runtime — the agent simply no longer
sees the function and cannot call it either.
Least privilege is the default: on a fresh machine every tool starts off. An agent gets the governance tools and nothing else until you decide what it may do.
Quick Start
git clone https://github.com/prinzalx/winadmin-mcp.git
cd winadmin-mcp
npm ci
npm run build
node dist/index.jsThe server announces where it lives — output, not arguments:
version v0.5.4
web interface http://127.0.0.1:8787
MCP transport stdio — this terminal stays attached to the agentOpen http://127.0.0.1:8787 in a browser and switch on what the agent may touch. Full walkthrough
for people who have never touched Node: docs/getting-started.md.
Related MCP server: winfolio
Documentation
Document | Contents |
install, build, start, first switches, design rules | |
all 46 switchable tools + 2 governance tools, inputs and answers | |
visible/approval switches, in-client popups, who may confirm | |
tabs, hover docs, master switches, HTTP endpoints | |
config.yaml, the windows-triage skill, why | |
CLI switches, environment variables, config file, audit trail | |
build/test commands, project structure, known limitations |
What It Feels Like
> hey hermes, my system crashed earlier — take a look at the event logs,
what could be the cause?Hermes calls system_health for the last boot, query_events for the window since then,
explain_event_id for Kernel-Power 41 or EventLog 6008, diagnose_service if a service was the
trigger — and quotes a stored learning if the team already decided that a given DCOM entry is
harmless. A sample skill for exactly this routine ships at
skills/windows-triage/SKILL.md.
The Shape of It
48 tools in tools/list, grouped in the dashboard as tabs:
Services · Events · Processes · Network · Diagnostics · Scheduler ·
Registry · Security · Monitor · Learnings — plus the two permanent governance tools
list_pending and confirm_action.
Every gated tool call asks for approval in the agent's own popup first (standard MCP
elicitation; Hermes shows it in hermes --tui), and only parks for the web dashboard when the
client cannot show one. By default an agent may not confirm its own parked action — the human
decides. See docs/governance.md.
License
MIT
Available Tools
2 toolsconfirm_actionConfirm actionB
Executes a destructive action that is waiting for approval, by its confirmation_id.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| confirmation_id | Yes | The id returned by the original tool call |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden, and it does flag the most important trait: the target action is destructive and is only being executed now after approval. It omits other consequential behavior — whether the confirmation is single-use/expiring, what authorization is required, and whether the effect is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the destructive nature and the required key stated up front, and no filler. Slightly terse for a destructive operation, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no annotations and no output schema, the description covers the core (destructive, awaiting approval, keyed by confirmation_id). It falls short on what the agent should expect after the call and on the lifecycle constraints of a pending confirmation, which matter more here because no structured fields cover them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single confirmation_id parameter, so the baseline is 3. The description restates the parameter name but adds no syntax, format, or provenance detail beyond what the schema's own 'id returned by the original tool call' already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (executes) and a specific resource (a destructive action awaiting approval), plus the mechanism (by confirmation_id). It is clearly distinguishable from the read-only sibling list_pending, though it never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: you call this once an action is 'waiting for approval' and you hold its confirmation_id. However, it never states that you should obtain the id via list_pending or the original tool call, nor any when-not-to-use condition (e.g. expired or already-confirmed requests).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_pendingList pending actionsB
List destructive actions waiting for approval.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
B3.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It hints that the listed items are destructive and need approval, but says nothing about whether listing itself is a safe read, whether it requires elevated permissions, pagination, or how results are ordered/returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler or redundancy. Nothing in it is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a trivial zero-param list tool with no output schema, the description is adequate to identify the tool but stops short of describing the shape of the pending-action records or pointing the agent to confirm_action as the next step. It is minimally sufficient rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the schema is empty and complete for this operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ("List") plus a precisely qualified resource ("destructive actions waiting for approval"). It is understandable in isolation, but it never mentions or distinguishes itself from the sibling confirm_action, which is the obvious downstream counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Waiting for approval" implies this is the queue you consult before calling confirm_action, so usage is inferable rather than stated. There is no explicit "use this when X, use Y when Z" routing, and no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v0.4.2- First observed
confirm_action - First observed
list_pending
TDQS
A3.5/5.0
Scored across 2 tools
Disambiguation5/5
The two tools have clearly distinct roles: one lists pending destructive actions and the other confirms a specific action by confirmation_id. There is no overlap in action or resource, so an agent can easily choose between them.
Naming Consistency5/5
Both tools use snake_case and follow a predictable verb_noun style (list_pending, confirm_action). No mixed casing or inconsistent verb conventions are present.
Tool Count3/5
Two tools is borderline thin for an admin approval workflow, even though each tool has a distinct purpose. The set would feel better scoped with at least one additional operation such as reject or cancel.
Completeness2/5
The surface covers listing pending actions and confirming them, but omits rejecting/denying, canceling, retrieving details, and viewing history. These are significant gaps for a safe destructive-action approval workflow.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Context and control for any AI. Agent identity, scoped access, and proof across tools.
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
Agent-native security, trust, reliability, data and procurement tools for AI workflows.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to perform comprehensive Windows system health diagnostics, security checks, developer workflows, and maintenance tasks via 85 tools with actionable recommendations, over MCP and OpenAI-compatible HTTP.MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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.2 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to safely perform file operations, run terminal sessions, manage processes, search content, and inspect Git repositories on a local Windows machine under configurable permission and audit controls.Apache 2.0