Vibe Annotations

What it does

Vibe Annotations is in two parts: a Chrome extension and a local server, published on npm as vibe-annotations-server. In the extension you click elements on a page of your app running on localhost, then write a comment or make design tweaks such as CSS value changes. The server keeps these annotations in ~/.vibe-annotations/annotations.json. Through MCP, a coding agent like Claude Code, Cursor or Windsurf can read them, look at the screenshot of the element, make the change in your source code, and then delete the annotation.

The server is a background process that listens on port 3846. It is not a command your client launches. Agents connect over Streamable HTTP at /mcp, or over the older SSE endpoint at /sse. The extension talks to the same process through a REST API at /api/annotations. With watch_annotations the agent can work hands-free: the call blocks until new annotations arrive. By default it stops after 300 seconds with nothing new, and the timeout goes up to 1800. read_annotations returns 50 annotations per page by default, up to 200.

The docs list six tools. The 0.5.3 code (lib/server.js) registers seven. The extra one is update_annotation, which writes generated design-variant scaffolding back to an annotation and moves it through its variants lifecycle.

What it needs

Node.js 18 or newer, plus the Vibe Annotations extension in Chrome. The server must be running before a client connects: run `npx vibe-annotations-server init` (an interactive wizard), or `npm install -g vibe-annotations-server` and then `vibe-annotations-server start`. Your client then connects to http://127.0.0.1:3846/mcp. Your app has to be served from a localhost-style address for the extension to annotate it.

Limits

The port is fixed at 3846 in the code, with no setting to change it. Only pages served locally can be annotated. get_project_context guesses the framework from common port numbers and does not inspect your project. Clients that only start stdio commands cannot use the server, because it speaks HTTP or SSE only. The repository is licensed under PolyForm Shield 1.0.0, not an open-source licence, although the npm README says MIT.

Who it suits

Suits front-end developers who want to point at things on a running local app and have a coding agent pick up the comments and design tweaks, without describing every element in chat. The agent edits your code with its own tools; this server only stores and serves the notes. It is a poor fit if your client cannot connect to a local HTTP MCP endpoint, if you do not use Chrome, or if you need to review deployed sites rather than localhost.