Snapstack Server

What bgaze/snapstack-server MCP server does

The bgaze/snapstack-server MCP server connects a browser capture extension to an MCP client through a local Node.js process. The extension sends encoded screenshots to the server, which stores them under ~/.snapstack/ by default. Each capture has an image file and a matching JSON file containing the page URL, title, timestamp, and dimensions.

The server exposes three MCP tools. get_screenshots returns a manifest containing stable capture numbers, absolute file paths, dimensions, and metadata; it does not return image bytes or remove files. count_screenshots reports how many captures are waiting. clear_screenshots deletes selected captures or the entire stack. Capture numbering restarts at 01 after the stack becomes empty.

This is intended for local browser-context workflows rather than general browser control. The companion extension performs the capture, encoding, downscaling, and full-page stitching before sending the result to the server.

How it works

The running process listens only on 127.0.0.1. The extension posts captures to /push, while MCP clients connect through /mcp when using Streamable HTTP. The same on-disk stack is available to the stdio MCP front end, which a client can spawn with snapstack mcp. HTTP requests are stateless, and capture intake remains handled by the always-on process independently of the MCP front end.

The server stores WebP or PNG captures with metadata sidecars. The extension can also use JPG according to the configured capture policy. MCP retrieval returns paths rather than embedding image data, allowing the client to read only the files it needs. Deletion is explicit: reading or counting captures never clears them.

Setup and configuration

To run the bgaze/snapstack-server MCP server, use Node.js 18 or newer, install the npm package globally with npm i -g snapstack-server, and enable the background service with snapstack enable. The service can start at login and restart after a crash. snapstack run starts the daemon in the foreground, while snapstack start, stop, and restart control it.

For HTTP clients, register http://127.0.0.1:4123/mcp after the server is running. For stdio clients, use npx -y -p snapstack-server snapstack mcp. The browser must also have the companion snapstack-extension loaded; the server alone does not capture browser tabs.

SNAPSTACK_DIR changes the stack directory and defaults to ~/.snapstack. SNAPSTACK_PORT changes the local listening port and defaults to 4123; the host remains 127.0.0.1. Capture settings are stored in ~/.snapstack/config.json and managed from the extension's options page. Supported settings include format, lossy quality, maximum width, and the maximum number of full-page slices.

Limitations and notes

The supplied material documents local HTTP and stdio transports but does not identify specific MCP client applications. The server requires the companion browser extension for capture intake. It does not provide browser navigation or interaction tools; its documented MCP operations concern listing, counting, and deleting stored screenshots. On Windows, the README advises using an Administrator terminal for global npm installation and scheduled-task registration.