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.
- **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 : 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:
The **daemon** self-updates on each (re)start/login; the **global CLI** (the snapstack command) does not.
Run snapstack update to bring **both** to the latest in one go.
The full end-to-end walkthrough (idiomatic install paths, MCP client registration, the extension) is in the
**extension README**.
MCP
SnapStack speaks two MCP transports over the same on-disk stack — pick whichever your client supports:
The HTTP /mcp endpoint is **stateless** (a fresh server + transport per request); the stdio front-end
(snapstack mcp) is spawned on demand and reads the same ~/.snapstack stack.
Capture intake (/push) always stays in the running server, independent of either MCP front-end.
Exposed tools
| Tool | Description |
|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| get_screenshots | Lists pending captures as a JSON manifest (stable number, absolute path, dimensions, metadata) — **no image bytes, no deletion**. Pass numbers (e.g. [1,3]) to list only those. |
| clear_screenshots | Deletes captures. Pass numbers to delete specific ones; omit to clear the whole stack. Numbering restarts at 01 once empty. |