Reading captures from a coding assistant (MCP)

SnapBuddy ships a small program that lets Claude Code, Claude Desktop, Cursor or any other MCP client read the captures you have already saved to a folder - so instead of pasting a bug report into a chat, you ask the assistant and it looks.

Connecting it

Copy the configuration out of SnapBuddy rather than typing one. Open Settings → AI agents and copy the Client configuration block. It is generated with your real access token already in it, and that is the point of it: a snippet assembled by hand out of the address field and the token field can leave SNAPBUDDY_MCP_TOKEN out, and a server started that way reads captures perfectly well while refusing every request for a new picture, for ever, with nothing anywhere to say the configuration is what is wrong. The block also pins the port the app is actually on, so it is right whether or not you have moved it. Cite: apps/desktop/src/settings.html, paintMcpConfig; the generated token and its refresh are pinned by a harness check in apps/desktop/test/checks.js.

One part is yours to fill in. The block contains <PATH-TO-SNAPBUDDY>; replace it with the folder you keep the SnapBuddy repository in. SnapBuddy cannot know that path, and the program is run out of a checkout today rather than installed alongside the app - apps/mcp is a private package, is not published to npm, and the installer does not ship it (tauri.conf.json bundles ffmpeg and two resource files). Anything you read elsewhere offering a one-word npx command is describing a future version.

And run pnpm install in that folder once. The server loads its libraries from the node_modules folder that command creates, so a copy of the repository nobody has installed stops before it starts - and your assistant will report that only as the server failing to start, without saying why. Installing once is enough; you do not repeat it per client.

Claude Code

One line, and the token goes in as an environment variable:

claude mcp add snapbuddy \
  --env SNAPBUDDY_MCP_TOKEN=the-token-from-Settings \
  -- node "<PATH-TO-SNAPBUDDY>/apps/mcp/src/index.mjs"

Claude Code also reads an mcpServers object from a .mcp.json file at the root of a project, which is the same shape the generated block already is, so pasting the block into that file is the same connection and travels with the project.

Claude Desktop

Claude Desktop keeps its servers in claude_desktop_config.json - on Windows in the Claude folder under %APPDATA%, on macOS under ~/Library/Application Support/Claude/. Add the snapbuddy entry from the generated block to it. If the file already lists other servers, keep them and add this one alongside - the block is a whole mcpServers object, so pasting over the file drops the others without an error, because what is left is still valid JSON. Written out:

{
  "mcpServers": {
    "snapbuddy": {
      "command": "node",
      "args": ["<PATH-TO-SNAPBUDDY>/apps/mcp/src/index.mjs"],
      "env": {
        "SNAPBUDDY_MCP_TOKEN": "the-token-from-Settings"
      }
    }
  }
}

Restart Claude Desktop afterwards. It reads that file when it starts.

Cursor

Cursor takes the same mcpServers object, in .cursor/mcp.json for one project or ~/.cursor/mcp.json for all of them. Check the filename against Cursor's own documentation before relying on it. The shape of the object is the one every client above uses and is not in doubt; where Cursor reads it from is Cursor's decision and has changed before, and this article would rather say so than send you to edit a file that is no longer read.

The rest of the environment

SNAPBUDDY_MCP_PORT only matters if you have moved the desktop app off its default port. The generated block carries whichever port SnapBuddy reports; a configuration written by hand needs the line only once the port has moved, and then it must match what Settings → AI agents → Address shows.

The server finds your capture folders by reading the desktop app's settings.json, so it needs no arguments and works with SnapBuddy closed. If you only use the extension, or keep captures elsewhere, set SNAPBUDDY_SAVE_DIR and SNAPBUDDY_VIDEO_DIR in the same env block.

It is not running unless you have added it yourself.

What it can answer

Tool	Answers
`list_captures`	What is on this machine, newest first, and what each one carries
`get_capture`	One capture as fields: status, note, the page, the environment, the dev log
`get_console_errors`	The console errors captured from the page, as data
`get_failed_requests`	The requests that errored or came back 400 or worse
`get_repro_steps`	The numbered steps reconstructed from what the recorder recorded
`get_frame`	One frame out of a recording, as an image
`get_document`	The markdown, exactly as SnapBuddy wrote it
`capture_region`	A NEW picture: the picker opens and you drag the box
`capture_screen`	A NEW picture of the whole screen, refused until you allow it

Six of the nine answer in text. get_frame costs vision budget, and the two capture_ tools cost that plus your attention - they are worth spending only when the pixels are the point, or when what you need to show the assistant is on your screen now and was never captured. Everything else about a capture is cheaper and more exact as text, which is the whole argument for this server over pasting a bundle in.

The two capture_ tools are listed even when nothing is set up, so an assistant that tries one gets a refusal telling it what to switch on rather than concluding the feature does not exist. They need SnapBuddy running with Settings → AI agents → Let agents reach SnapBuddy turned on, and the access token shown there set as SNAPBUDDY_MCP_TOKEN in this server's entry in your client config - which is what the generated Client configuration block above already does for you. Reading needs none of that.

Two things that are easy to read wrong

captured: false is not "nothing went wrong". Console and network capture is off until a tester switches it on for a site, and a recording has no card data at all - so an empty get_console_errors can mean nobody was looking. The answer says which, in a note. An agent that reports "there were no console errors" about a capture that never looked is worse than one that says nothing.

get_frame needs ffmpeg, and it looks in this order: SNAPBUDDY_FFMPEG if you set it, then the one the desktop app ships (its release build, its debug build, then the fetched sidecar), then ffmpeg on PATH. If none is there it says so and names every place it looked - pnpm ffmpeg in the repo fetches the pinned one. The frame returned is the nearest keyframe at or before the time asked for, and the answer says which second it landed on rather than echoing the request.

What it can and cannot see

Only what you have saved to a folder. Cards live in the app until you press Save files, so a board full of work can leave this empty. That is not a fault; save the card and it appears.

Not the apps' own storage. A separate program cannot open the desktop's or the browser's internal database, which is why the folder is the boundary.

Older captures work with less detail. Cards saved before SnapBuddy started writing a small data file beside the picture are recovered from their Markdown instead. get_capture says from: "document" when that happened, and marks the developer log partial if the document had shortened it - a log that looks complete and is not is worse than no log.

The thing worth understanding before you connect it

Nothing it does leaves your computer. It opens files and hands back what it finds, and it never writes to them, uploads anything or phones home. The one connection it makes at all is to SnapBuddy itself on this machine's loopback address, to pass on a request for a new picture. Both of those are checked by the build (scripts/check-promises.mjs), not just claimed here - a host that is not loopback fails it.

But what it answers with goes to the assistant that asked. Your note, the page you were testing, and the console messages and request addresses captured from that page all reach that assistant - and most of them run in the cloud. The file never leaves your disk; the contents do. It is the same trade as pasting a bug report into a chat window, and it is worth knowing it is the trade.

If a capture contains something you would not paste into a chat, do not point an assistant at it.

Support answer, ready to paste

The MCP server reads captures you have saved to a folder, and it sends nothing off your computer. It can also ask SnapBuddy for a new screenshot, but only while you have that switched on in Settings, and a region capture opens the picker so the drag is yours. Whatever it answers with goes to the assistant you connected it to, which usually runs in the cloud - so treat it like pasting the capture into that assistant's chat window.