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.

⚠️ 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 — right-click → Run as Administrator, then:
"mcpServers": { "system-admin-mcp": { "command": "uvx", "args": ["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.

Manual Setup

If you don't have just installed:

Run terminal AS ADMINISTRATOR first, then:

uvx system-admin-mcp
See Quickstart for full setup.

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
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
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.2 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 14-page React SPA on ports 10860 (frontend) / 10861 (backend):

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

Pages: Dashboard, Status, Processes (paginated, sortable), Services (paginated), 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 mcpb-pack`	Build MCPB bundle
`just build`	Install dependencies
`just web`	Start FastAPI backend on 10861
`just web-frontend`	Start Vite frontend on 10860

Project Map

├── AGENTS.md           # Instructions for AI agents
├── justfile            # Task runner (SOTA Industrial Dashboard)
├── pyproject.toml      # Python project config (FastMCP 3.2)
├── 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.