winadm MCP server
Commit Nov 11, 2026Enables AI agents to manage Windows services, processes, event logs, and PowerShell commands with a read-only by default security model.
Also known as technothatch/winadm-mcp
- Stars
- 0
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- MIT
What is winadm MCP?
winadm enables AI agents to manage Windows services, processes, event logs, and PowerShell commands with a read-only by default security model. It exposes 7 tools, such as list_windows_services, service_action_tool, list_windows_processes.
Summary generated from the project's README
About winadm MCP server
Managing Windows services, processes, and event logs through an AI agent is what winadm-mcp enables. This server provides a way for developers to use Claude Desktop or Claude Code to diagnose system issues like high RAM usage or service failures without manually opening Task Manager or Event Viewer. It works locally on Windows systems and offers a security-first approach by remaining in a read-only mode by default.
Users can grant administrative permissions by starting the server with the --allow-write flag. Once enabled, the agent can use the service_action_tool to restart services, the kill_process_tool to stop specific PIDs, and the run_powershell_command_tool to execute custom scripts. The server includes built-in safety measures such as regex validation for service names and PIDs to prevent injection. For long-running tasks, the PowerShell tool provides progress notifications and returns partial output if a timeout occurs, which is controlled by the WINADM_COMMAND_TIMEOUT variable.
What you can do with it
- 1Diagnose service failuresAsk an AI agent to identify why a specific Windows service has stopped running.
- 2Monitor system resource usageHave an agent investigate which processes are consuming the most memory or CPU.
- 3Review system error logsRequest a summary of recent critical or warning events from the Windows system log.
- 4Execute administrative PowerShell scriptsInstruct an agent to run specific PowerShell commands to perform system administration tasks.
Written from the project's README. Every use case is checked against a quote from it.
winadm MCP tools 7
Detected from the READMElist_windows_servicesservice_action_toollist_windows_processeskill_process_toolread_eventlogrun_powershell_command_toolwindows_system_info
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletechnothatch/winadm-mcp is public and reachablegithub.com/technothatch/winadm-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/technothatch/winadm-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubwinadm-mcp
An MCP server that gives AI agents safe, read-mostly access to Windows administration: services, processes, the event log and system info.
$ pip install git+https://github.com/technothatch/winadm-mcp
$ winadm-mcp --allow-write
Point Claude Desktop / Claude Code / any MCP client at it and your agent can answer
"why is my printer not working" (Spooler stopped?), "what ate my RAM" or
"what broke since boot" — without you alt-tabbing through services.msc,
Task Manager and Event Viewer.
Tools
| Tool | Access | What it does |
|---|---|---|
list_windows_services |
read | all services with status + start type; filter by status/name |
service_action_tool |
write | start / stop / restart a service |
list_windows_processes |
read | PID, working set MB, CPU seconds |
kill_process_tool |
write | force-kill by PID |
read_eventlog |
read | newest events from any log (default System, error/warning/critical) |
run_powershell_command_tool |
write | run a PowerShell command and return its output (with progress notifications) |
windows_system_info |
read | OS, hostname, last boot, memory totals |
Read-only by default. Write tools refuse to act unless the server is started with
--allow-write. Service names and PIDs are validated before they touch PowerShell.
The story behind it: Give Windows administration tools a defined boundary — the TechnoThatch journal piece on the read-only-by-default design.
Install / run
Status: not on PyPI yet. Install from GitHub until it is published:
pip install git+https://github.com/technothatch/winadm-mcp winadm-mcp # read-only (recommended first) winadm-mcp --allow-write # enable write toolsThe
uvx winadm-mcp/pip install winadm-mcpforms will work once the package is on PyPI.
Claude Desktop config example (after pip install, use the winadm-mcp entry point
directly — uvx only works once the package is on PyPI):
{
"mcpServers": {
"winadm": {
"command": "winadm-mcp",
"args": []
}
}
}
Long-running commands
run_powershell_command_tool sends MCP progress notifications while a command is
still running: elapsed time, and the last line the command printed. MCP clients give up
on calls that stay silent (Claude Code aborts after 300 s with "sent no response or
progress"), so a long command that says nothing looks exactly like a hung one.
[progress] 10.1/120.0 running 10s - last output: step 8
When the command exceeds its timeout, the tool returns the output produced so far plus how long it ran, instead of a bare "timed out":
started
[timed out after 6s - the PowerShell process was ended, but programs it started may still be running]
A timeout stops the PowerShell process only. Programs the command started
(Start-Process firefox, a build kicked off by a helper) keep running — a killed GUI
app or an interrupted build cannot be brought back, and an agent can always see and
end a leftover console process itself.
Two environment variables tune this:
| Variable | Default | Effect |
|---|---|---|
WINADM_PROGRESS_INTERVAL |
10 |
seconds between progress notifications |
WINADM_COMMAND_TIMEOUT |
120 |
seconds before a command is stopped |
Honest technical notes
- Every tool is a small PowerShell one-liner invoked with
-EncodedCommand(UTF-16LE base64, no temp files, no shell string interpolation of user input — names/PIDs are regex-validated first). - Output is read on background threads. A descendant that inherits the pipes can keep them open, so waiting for them is deliberately bounded — a slow pipe never hangs the tool call.
- A timeout kills the PowerShell process, never the process tree (
taskkill /Talso kills GUI programs the command meant to outlive it). - Windows-only by nature; on other OSes tools return a clear error instead of lying.
- Tested on Linux CI with fully mocked PowerShell (deterministic, no admin rights needed)
and smoke-tested on
windows-latest.
Development
pip install -e ".[dev]"
pytest
License
winadm MCP questions
What tools does winadm MCP provide?
It exposes 7 tools, including list_windows_services, service_action_tool, list_windows_processes, kill_process_tool, read_eventlog.
Is the server safe to use with AI agents?
Yes, it is read-only by default. Write tools like starting services or killing processes only work if you explicitly start the server with the --allow-write flag.
How do I enable write access for services and processes?
You can enable write access by running the server with the --allow-write argument.
What happens if a PowerShell command takes too long to run?
The server sends progress notifications during execution. If a command exceeds the timeout, it returns the output produced so far and stops the PowerShell process.
Can I use this on Linux or macOS?
No, this is a Windows-only tool. On other operating systems, the tools will return an error.