MCP (local agent)
About 1 minute to set up. Then write notes in the browser, and your agent picks them up.
How it works
Your agent starts spotnote-mcp, a small server on your machine. Your app sends it each note you write, and your agent, watching, gets it through the MCP tools. The agent's answer goes back the same way, and shows on the note.
Set up
Add the server to your agent (once)
Pick your agent:
claude mcp add --scope user spotnote -- npx -y spotnote-mcpOr let your agent add it: the spotnote-setup skill does this step too.
There's nothing else to run. The agent starts the server, and the launcher in your app connects to it on its own.
You should see Connected under Settings → MCP once your agent is running.
Port 4848 taken?
Set the same free port in two places:
- Your agent: add
-e SPOTNOTE_PORT=4900to the Claude Code command, or"env": { "SPOTNOTE_PORT": "4900" }next to"args"in a JSON config. - Your dev server:
spotnote({ port: 4900 })in your Vite config (seeport), orSPOTNOTE_PORT=4900 pnpm dev.
Write notes in the browser
MCP Tools
| Tool | What it does |
|---|---|
watch_notes | Waits up to 50 seconds for notes that need the agent (new notes and your replies), then returns them. The agent calls it in a loop. |
list_notes | Returns every open note. |
reply_note | Writes a message to you on a note, usually a question. |
dismiss_note | Closes a note without making the change, with the reason. |
resolve_note | Marks a note done, with a short summary of the change. |
Each note comes with its id, its page, the same prompt that copying gives you, and the conversation so far.
Where notes live
spotnote-mcp keeps your notes in ~/.spotnote/, so every browser shows the same ones. See Storage.
It listens on 127.0.0.1 only, so other devices on your network can't reach it.
Next
Concepts: how Spotnote finds an element's file and line.