mcp-notes-server
This MCP server provides a local, searchable notes memory for an AI assistant.
Save new notes with title, content, and optional tags.
Fetch a single note by id with full content.
List notes newest first, optionally filtered by one tag.
Keyword-search note titles, tags, and bodies, with a result limit.
Update a note's title, content, and/or tags (tags replace existing tags).
Permanently delete a note by id.
Export all notes or one tag's notes as a single Markdown document.
The provided schema exposes these 7 tools; the README also mentions list_tags, resources (notes://all, notes://{id}), and a review_notes prompt.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-notes-server Save a note titled RAG chunking: use 800-char chunks with overlap, tagged rag."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-notes-server
An MCP server that gives Claude and other AI assistants a searchable notes memory, stored in one local JSON file.
mcp-notes-server is a Model Context Protocol (MCP) server written in TypeScript. Connect it to Claude Desktop, Claude Code or any MCP client and your AI assistant can save, search, edit, export and delete notes that survive between chats: simple AI assistant memory you own, on your disk, with no cloud and no network calls.
Quick start (60 seconds)
You need Node.js 18 or newer.
# Claude Code
claude mcp add notes -- npx -y mcp-notes-serverFor Claude Desktop, add this to claude_desktop_config.json (Settings, Developer, Edit Config), then fully quit and restart the app:
{
"mcpServers": {
"notes": {
"command": "npx",
"args": ["-y", "mcp-notes-server"]
}
}
}Then type: "Save a note titled RAG chunking: use 800-character chunks. Tag it rag." and "Search my notes for chunking."
Prefer a clone? git clone https://github.com/techsaurabh-394/mcp-notes-server && cd mcp-notes-server && npm install && npm run build, then use "command": "node" with "args": ["/absolute/path/to/mcp-notes-server/dist/index.js"] (print it with echo "$(pwd)/dist/index.js"). Relative paths fail because the app starts the server from another folder.
Related MCP server: mcp-server-example
Tools
Tool | What it does | Inputs | Side effects |
| Save a new note, returns its id |
| Writes the notes file |
| Fetch one note with full content |
| None (read-only) |
| List notes newest first, titles and tags only |
| None (read-only) |
| Keyword search over titles, tags and bodies |
| None (read-only) |
| Edit title, content and/or tags (tags replace the old ones) |
| Rewrites the notes file |
| Permanently delete one note |
| Rewrites the notes file. Marked |
| Return all notes (or one tag) as one Markdown document |
| None (read-only, nothing is written to disk) |
| List every tag in use with its note count, most used first | None | None (read-only) |
The server also exposes the resources notes://all and notes://{id}, and a review_notes prompt that asks the model to summarise and tidy your notes.
Every tool has a typed zod input schema and MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so clients can show the right confirmation UI. Invalid input returns a clear error and stores nothing.
Example prompts
"Save a note titled Docker tips: use multi-stage builds to keep images small. Tag it docker and devops."
"Search my notes for docker and summarise what I wrote."
"Change the tags on that note to docker, images."
"List everything tagged devops, then export those notes as Markdown."
"Delete the note about Docker tips."
How it works
Your 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 with
zodand the store's own limits.Writers take a lock file, write a temp file, then rename it over
notes.json. A crash never leaves half a file.The result goes back to the model as text.
Storage. One JSON file: ~/.mcp-notes/notes.json, or the path in the NOTES_FILE environment variable. Each note has id (8 hex characters), title, content, tags (lowercased, de-duplicated) and createdAt (ISO timestamp).
Search. For each search word: +3 if it is in the title, +2 if it matches a tag exactly, +1 if it is in the body. Scores add up, highest first, zero scores are dropped. It is plain keyword matching, not semantic search.
Limits. Title 200 characters with no line breaks, content 20,000 characters, 10 tags of at most 50 characters each, 5,000 notes per file. A notes file with malformed entries is refused rather than overwritten.
Two clients at once. Writes hold an exclusive lock file (notes.json.lock) for the read-modify-write cycle. A lock older than 30 seconds is treated as left behind by a crash and removed. A test starts four separate OS processes that add 15 notes each and checks all 60 survive.
Optional: human approval before delete
By default delete_note runs immediately. To require approval, install mcp-safe-actions next to the server and set NOTES_CONFIRM_DELETE=1:
npm install github:techsaurabh-394/mcp-safe-actions # in the folder that holds mcp-notes-server{
"mcpServers": {
"notes": {
"command": "node",
"args": ["/absolute/path/to/mcp-notes-server/dist/index.js"],
"env": { "NOTES_CONFIRM_DELETE": "1" }
}
}
}delete_note then uses registerConfirmedTool: clients that support MCP elicitation ask you directly; others get a one-time token the model must pass back. Nothing is deleted before approval. Extra variables: NOTES_CONFIRM_MODE (auto, elicit or token) and NOTES_AUDIT_FILE (path for a JSON-lines audit log). If the package is missing, the server refuses to start instead of silently running unguarded. mcp-safe-actions is not on npm yet, so it is installed from GitHub.
Security notes
No shell, no SQL, no network calls: the server only reads and writes one JSON file.
The file path comes from the operator (
NOTES_FILE), never from tool input. Ids are never used as paths, andget_note/update_note/notes://{id}reject ids that are not 8 hex characters.stdout is the protocol channel. All logging goes to stderr (a test checks every stdout line is a JSON-RPC message).
Not covered: notes are plain text with no encryption or access control beyond your operating system's file permissions. Anything in a note is visible to the AI model that reads it, so do not store secrets in notes. Do not point several machines at one file over a network share: the lock file is only safe on a local filesystem.
Report vulnerabilities as described in SECURITY.md.
Development and tests
npm install
npm run lint # tsc --noEmit
npm test # build, then node:test
npm run coverage # same, with Node's built-in coverage reportThe suite has store unit tests (limits, locking, stale locks, export) and end-to-end tests that 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. CI runs on Node 18, 20 and 22 and prints the coverage table to the job summary. See CONTRIBUTING.md and CHANGELOG.md.
Roadmap
Typed tools, resources and a prompt
Input limits, lock-file safe writes, Markdown export
Optional human approval for delete
Publish to npm
Optional SQLite backend for large collections
Semantic search with embeddings
Streamable HTTP transport for remote clients
Import from Markdown
FAQ
Where are my notes? In ~/.mcp-notes/notes.json, or at your NOTES_FILE path. Changing NOTES_FILE shows a different, empty set of notes.
Does it send my notes anywhere? The server makes no network calls. But your AI app sends the notes it reads to its model provider as part of the conversation.
Does it work with clients other than Claude Desktop? It speaks standard MCP over stdio, so Claude Code, Cursor and other MCP clients can run it. Only Claude Desktop and Claude Code are documented here.
The server does not show up. Run node dist/index.js yourself: it should print mcp-notes-server running on stdio to stderr. Check that the config JSON is valid, the path is absolute, and you fully restarted the app. If the app cannot find node, put the full path from which node in "command".
Is search semantic? No. It is keyword scoring over titles, tags and bodies.
Can I back up my notes? Copy the JSON file, or ask the assistant to run export_notes and save the Markdown.
Contributing
Small, focused pull requests are welcome. Read CONTRIBUTING.md, and look for issues labelled good first issue. Please follow the Code of Conduct.
Support this project
If this saves you time, a star helps others find it, and you can support more free open-source work:
Author
Saurabh Pathak, AI engineer and full-stack developer.
GitHub · LinkedIn · Blog: mernstackdev.com
License
Available Tools
7 toolsadd_noteAdd noteA
Save a new note. Returns the note id. Use tags to group related notes.
Inputs: title (required), content (required), tags.
delete_noteDelete noteADestructiveIdempotent
Permanently delete one note by id. This cannot be undone.
Inputs: id (required).
export_notesExport notesARead-only
Return all notes (or only those with one tag) as one Markdown document, newest first. Read-only: nothing is written to disk.
Inputs: tag.
get_noteGet noteARead-only
Fetch one note by id, with full content.
Inputs: id (required).
list_notesList notesARead-only
List notes, newest first. Optionally filter by a single tag.
Inputs: tag.
search_notesSearch notesARead-only
Keyword search across note titles, tags and bodies. Returns the best matches with full content.
Inputs: query (required), limit.
update_noteUpdate noteAIdempotent
Edit an existing note. Provide the id and at least one of title, content or tags. Tags, if given, replace the existing tags.
Inputs: id (required), tags, title, content.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct action on notes: create, read one, list, keyword search, update, delete, and export. The retrieval tools (list, search, export) have clearly differentiated behaviors described explicitly, so an agent can pick correctly.
All seven tools follow a strict verb_noun snake_case pattern (add_note, get_note, list_notes, update_note, delete_note, search_notes, export_notes). No mixing of conventions.
Seven tools is a well-scoped set covering the full note lifecycle plus search and export. Every tool earns its place with no redundant entries.
Complete CRUD coverage (add/get/list/update/delete) plus search and export, leaving no obvious dead ends. Minor extras like tag listing or bulk delete are not essential to the domain.
Maintenance
Related MCP Connectors
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Save notes in seconds. Your AI can then search, read, write and tag them over MCP.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides persistent, searchable memory for MCP-compatible AI coding tools, allowing notes added from one tool to be retrieved from another.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage in-memory notes by listing, fetching, and creating notes through MCP tools over stdio.138 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables managing plain-text notes on disk through MCP resources, tools, and prompts, so natural-language requests can create, read, search, delete, and summarize notes via an interactive client.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to read, search, create, update, and remove locally stored personal notes organized by themes and subt themes, with backlink navigation, all through MCP tools.MIT