mcp-notes-server: giving Claude a notes memory that lives in one JSON file

Saurabh Pathak — Mon, 26 Oct 2026 10:29:17 +0000

Every chat with an AI assistant starts from zero. I wanted Claude to be able to remember things between conversations, with the notes on my own disk and no cloud service involved.

mcp-notes-server is a Model Context Protocol (MCP) server in TypeScript. Connect it to Claude Desktop, Claude Code or any MCP client and the assistant can save, search, edit, export and delete notes that survive between chats. Everything sits in one local JSON file, and the server makes no network calls.

Repo: https://github.com/techsaurabh-394/mcp-notes-server
npm: https://www.npmjs.com/package/mcp-notes-server

Try it in one line with Claude Code:

claude mcp add notes -- npx -y mcp-notes-server

Then ask: "Save a note titled RAG chunking: use 800-character chunks. Tag it rag." and later "Search my notes for chunking."

How it works

The AI app starts the server as a child process and talks to it over stdio using JSON-RPC. The model reads the tool list and picks a tool. The server validates the input and sends the result back as text.

There are 7 tools:

add_note, get_note, list_notes, search_notes, update_note, delete_note and export_notes. There are also two resources (notes://all and notes://{id}) and a review_notes prompt. Every tool has a typed zod schema and MCP annotations (readOnlyHint, destructiveHint and so on), so clients can show the right confirmation UI. Bad input returns a clear error and stores nothing.

Search

Search is deliberately simple keyword scoring: +3 if a word is in the title, +2 if it matches a tag exactly, +1 if it is in the body. Scores add up, highest first. It is not semantic search, and I say so in the README. Embeddings are on the roadmap.

Safe writes

The part I spent the most time on was making the file safe to write:

Writers take a lock file, write a temp file, then rename it over notes.json, so a crash never leaves half a file.
A lock older than 30 seconds is treated as left behind by a crash and removed.
A notes file with malformed entries is refused, not overwritten.
A test starts four separate OS processes that add 15 notes each and checks that all 60 surviv e.

Security choices

No shell, no SQL, no network calls.
The file path comes from the operator (NOTES_FILE), never from tool input. Ids are 8 hex characters and are never used as paths.
stdout is the protocol channel, so all logging goes to stderr, and a test checks that every stdout line is a JSON-RPC message.
Optional human approval for delete_note through a companion package, mcp-safe-actions.

What I learned

stdout belongs to the protocol. One stray console.log breaks an MCP server. Sending logs to stderr and testing for it saved me from a confusing class of bugs.
End-to-end tests beat unit tests for MCP. The most useful tests spawn the built server over stdio with the MCP SDK client and call every tool with valid input, invalid input, empty results and unknown ids.
Say what it does not do. Notes are plain text with no encryption, and the model sees whatever it reads. Putting that in the README is better than letting people assume otherwise.
Publishing is its own task. Getting the package onto npm, with CI on Node 18, 20 and 22, took as long as some of the features.