win-reg-mcp

Local Python MCP server for semantic search and controlled changes across HKLM, HKCU, HKCR, HKU, and HKCC, in both 64-bit and 32-bit Registry views. The process must run elevated as Administrator.

Setup

Install Python 3.11+, Ollama, and the project dependencies in an Administrator PowerShell:

ollama pull qwen2.5:7b
ollama pull nomic-embed-text
ollama pull qwen2.5vl:7b  # optional; used only for screenshot/webcam descriptions
python -m pip install -e ".[dev]"

Start with python -m win_reg_mcp. The initial scan runs before MCP becomes available (default startup timeout: one hour; override with --startup-timeout). Existing explanations and embeddings are cached in SQLite; unchanged values are not sent to the LLM again. The server exposes exactly three MCP tools: Search, Rollout, and Rollback.

python -m win_reg_mcp --database "$env:LOCALAPPDATA\WinRegMCP\registry.sqlite3" --workspace-root "C:\Work"

Rollout creates and commits a SQLite snapshot of every target value before applying any change. Rollback restores the newest successful rollout. File write/delete agent tools are restricted to configured --workspace-root paths (or the current directory when none is configured).

Related MCP server: SystemLens

Build and validation

Run scripts\format.ps1, scripts\test.ps1, and scripts\build.ps1 from PowerShell. The ZIP contains source and the complete PyInstaller command, not a prebuilt binary: run scripts\build.ps1 on Windows to create dist\win-reg-mcp.exe (PyInstaller builds for its host OS).