system-admin-mcp

System Admin MCP

📖 Installation Guide — quick start, manual setup, and troubleshooting

Windows system administration, through AI. File recovery, security, disk maintenance, diagnostics, services, processes — all accessible via MCP (Claude Desktop, Cursor, etc.) and a React web dashboard.

Download the installer: latest release (system-admin-mcp-0.4.0-setup.exe) — no Python needed, backend embedded. For Claude Desktop without installing: attach system-admin-mcp-0.4.0.mcpb from the same release.

Claude Desktop only — one-line install of the latest bundle:

irm https://github.com/sandraschi/system-admin-mcp/releases/latest/download/install.ps1 | iex

⚠️ Administrator privileges required. Disk operations, service management, file recovery, and permission changes need elevation. Run your terminal as Administrator before starting the server.

// Claude Desktop — from source (no registry package; see INSTALL.md):
{ "mcpServers": { "system-admin-mcp": {
  "command": "uv",
  "args": ["--directory", "D:\\Dev\\repos\\system-admin-mcp", "run", "system-admin-mcp"]
} } }

---

Quick Start

git clone https://github.com/sandraschi/system-admin-mcp
cd system-admin-mcp
just

This opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start. Frontend deps install via Bun 1.3+ (bun.lock committed); Node 22+ stays for the Vite/Tauri CLIs.

Manual Setup

If you don't have just installed:

Run terminal AS ADMINISTRATOR first, then:

git clone https://github.com/sandraschi/system-admin-mcp
cd system-admin-mcp
uv sync --all-extras
uv run system-admin-mcp         # stdio mode (for MCP clients like Claude Desktop)
uv run system-admin-mcp --web   # HTTP mode on :10861 (web dashboard backend)

Verify: Invoke-WebRequest http://127.0.0.1:10861/api/health -UseBasicParsing → 200. See INSTALL.md for prerequisites, installer/MCPB options, and troubleshooting.

What You Can Do

Area	Operations
System Health	CPU/RAM/disk metrics, event logs, hardware inventory, installed software
File Recovery	Scan NTFS MFT, recover deleted files, validate integrity
Security	View/set/audit NTFS permissions, take ownership, network port audit, Defender/VPN/Tailscale posture, red-button Airgap
Disks	SMART health, defrag (HDD), TRIM (SSD), cleanup, folder size analysis
Services	List/start/stop, change startup type, paginated
Processes	List/sort/analyze/kill, paginated, sortable by CPU/Memory/Name/PID
Startup & Taskbar	Manage startup programs, toggle autohide, find blockers, taskbar buttons + tray icons with autostart flags
AI Chat	Local (Ollama/LM Studio) + 13 cloud providers via backend proxy, streaming, resident-first GPU placement
Safety	Read-only mode (SYSTEMADMIN_READ_ONLY=1), mutation audit log, confirm-gated Airgap (see docs/SECURITY.md)
Agentic	Let AI autonomously diagnose and fix issues (SEP-1577 sampling)

All operations go through a single system_admin tool — one tool, 40+ operations.

---

FastMCP 3.4 Capabilities

Feature	What it provides
ctx.sample() (SEP-1577)	Server-side LLM calls for autonomous diagnosis. Tools agentic_system_workflow and autonomous_system_troubleshooter use ctx.sample() to orchestrate multi-step diagnostics without client round-trips — the server borrows the client LLM to interpret system data and recommend actions.
Prompts (4 templates)	Registered via @mcp.prompt(): system_diagnostics_expert, security_hardening_expert, system_troubleshooter, volume_maintenance_expert. Each has parameterized focus modes (e.g. performance vs events, ownership vs audit). Clients inject them as system instructions.
Skills (skill://)	SkillsDirectoryProvider exposes skill://system-admin-expert/SKILL.md — a portable expertise document with safe-mode patterns, diagnostic sequences, and SEP-1577 workflow recipes. Discoverable via resources/list.
Prefab UI (4 cards)	@mcp.tool(app=True) tools returning ToolResult with structured_content=PrefabApp(...): system_health_card (CPU/RAM/disk), top_processes_card (sorted by CPU/memory), list_services_card (filtered services), volume_status_card (all volumes with bar charts). Rendered natively by capable hosts (Claude Desktop side-panel).
CodeMode	BM25 discovery for agentic tool selection. Enabled via --agentic flag.
SkillsDirectoryProvider	Registers skill:// resources from skills/ directory.
Dual transport	stdio (default for Claude Desktop) + streamable-http (MCP_TRANSPORT=http).

---

Web Dashboard

A 20-page React SPA on ports 10860 (frontend) / 10861 (backend):

just web              # Backend API
just web-frontend     # Frontend dev server

Pages: Dashboard, Inbox (attention feed), Status, Processes (paginated, sortable), Services (paginated), Taskbar (buttons + tray + autostart), Volumes, File Owner, File Recovery, Logs, Tools, Apps, Elevated, Chat, Settings, Help.

---

Justfile Commands

Command	What it does
just dev	Start MCP server (Claude Desktop)
just serve	Start MCP via HTTP
just test	Run tests
just lint	Check code quality (ruff + biome)
just fix	Auto-fix everything
just certify	Full gates: ruff + format + pyright + pytest + frontend build + biome
just mcpb-pack	Build MCPB bundle
just build	Install dependencies
just web	Start FastAPI backend on 10861
just web-frontend	Start Vite frontend on 10860

---

Stack

React 19 + Vite 7 + TailwindCSS 3 + Radix UI + Lucide + TanStack Query + Zustand 5 (LLM/GPU store) + React Router 7. Backend: FastAPI + FastMCP 3.4 (fastmcp[tasks]>=3.4.4,<4) on Python 3.12+, uv managed. No Bootstrap, no jQuery, no Redux.

Environment

Var	Default	Effect
SYSTEMADMIN_READ_ONLY=1	off	Mutation kill switch
SYSTEMADMIN_LLM_KEYSTORE	data/llm_keys.json	0600 LLM key store
MCP_TRANSPORT=http	stdio	Streamable-HTTP transport
WEBAPP_PORT / PORT	10861	Backend port

Full install + troubleshooting: INSTALL.md.

---

Project Map

├── AGENTS.md           # Instructions for AI agents
├── justfile            # Task runner (SOTA Industrial Dashboard)
├── pyproject.toml      # Python project config (FastMCP 3.4)
├── src/system_admin_mcp/
│   ├── app.py          # FastMCP instance + lifespan (skills, prefabs)
│   ├── server.py       # FastAPI backend (20+ REST endpoints)
│   ├── transport.py    # stdio / streamable-http dual transport
│   ├── prompts.py      # 4 @mcp.prompt() templates
│   ├── tools/
│   │   ├── portmanteau.py          # system_admin (40+ ops dispatcher)
│   │   ├── implementations.py      # File recovery, ACLs, disk, WMI
│   │   ├── services_and_tasks.py   # Services, processes, startup, taskbar
│   │   ├── agentic_system_workflow.py  # ctx.sample() workflows
│   │   ├── monitoring.py           # Watchdog file watcher
│   │   ├── system_ops.py           # Standalone tools
│   │   └── prefab/                 # 4 Prefab UI cards
│   ├── elevated_service/           # Named-pipe elevated bridge
│   └── user_bridge/                # Service communication client
├── web_sota/           # React 19 + Vite dashboard
├── mcpb/               # MCPB packaging (v0.2 manifest)
├── skills/             # skill://system-admin-expert/SKILL.md
└── tests/              # Pytest suite

---

Docs

Document	For
Quickstart	End users — install, configure, run
API Reference	Developers — REST endpoints
Development	Contributors — hacking on the server
AGENTS.md	AI agents — architecture & patterns

---

Built by Sandra Schipal in Vienna. MIT.