io.github.bgaze/snapstack-server

The SnapStack server is a single always-on Node process: it receives browser captures from the extension, stacks them on disk, and serves them to any MCP-capable LLM client over Streamable HTTP. It listens only on 127.0.0.1 — nothing ever leaves your machine.

New here? The full install + usage guide lives in the extension README: snapstack-extension. This page is the technical reference.

Architecture

One always-on process serves both the extension (capture) and your MCP client, decoupled by a folder on disk.

[MV3 extension]  --POST /push (bytes) ┐
                                      ▼
                              [SnapStack server - 127.0.0.1:4123]   
                                 ├─ writes           →  stack on disk
                                 └─ MCP /mcp (HTTP)  ←  MCP client

• Capture — the extension encodes the shot as WebP (PNG fallback), downscales it, and POSTs it here.
• Stack — one image file (.webp/.png) plus a twin .json (url, title, timestamp, dimensions) per capture, named NN <timestamp>: a stable two-digit number (assigned in capture order, restarts at 01 when the stack empties) plus a timestamp, under ~/.snapstack/.
• Retrieval — get_screenshots returns a JSON manifest (number, absolute path, dimensions, metadata — no image bytes); the client reads only the files it needs, by path. Deletion is a separate, explicit clear_screenshots step. Retrieval never deletes.

Requirements

• Node.js ≥ 18 (tested on Node 20). No git needed at runtime.
• An MCP-capable LLM client speaking the HTTP (Streamable HTTP) or stdio transport.
• The snapstack-extension loaded in your browser.

Install & run

On Windows, use an Administrator terminal, otherwise the global npm install and the scheduled-task registration may get rejected.

The server ships on npm and installation is straightforward on macOS, Linux and Windows:

1. Install globally: npm i -g snapstack-server
2. Enable background service: snapstack enable

SnapStack auto-starts on login, restarts on crash, and updates itself on each launch.
To check its status or if an update is available, simply run snapstack in your terminal.

Available commands:

snapstack                            # status report: service + server health, update check
snapstack start | stop | restart     # control the running service (this session)
snapstack update                     # update the CLI (npm i -g) + restart the server on the latest
snapstack run                        # run the daemon in the foreground (no auto-start)

The daemon sel

... View full README on GitHub