sample-notes-mcp-server
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., "@sample-notes-mcp-server add a note: buy groceries"
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.
sample-notes-mcp-server
A tiny Model Context Protocol (MCP) server for saving, listing, searching, and deleting text notes — over stdio.
It knows nothing about any particular client. It just speaks MCP over stdio, so any MCP client (Claude Desktop, Claude Code, or your own) can use it. Notes persist as a JSON file on disk.
Install
No install required — run it straight from npm with npx:
npx sample-notes-mcp-serverOr install it globally:
npm install -g sample-notes-mcp-server
sample-notes-mcp-serverRelated MCP server: live2d-mcp
Usage
sample-notes-mcp-server [notes-file]notes-file(optional) — path to the JSON file where notes are stored. Defaults to./notes.jsonin the current working directory. The file is created on first write.
The server communicates over stdio: stdout is reserved for the MCP protocol, so all human-facing logging goes to stderr. You normally don't run it by hand — an MCP client launches it for you (see below).
Tools
Tool | Arguments | Description |
|
| Save a short text note. Returns the new note's id. |
| (none) | List all saved notes. |
|
| Find notes containing |
|
| Delete a saved note by its id. |
Each note is stored as { id, text, createdAt }, where id auto-increments and createdAt is an ISO 8601 timestamp.
MCP client configuration
Add the server to your MCP client's config. Most clients use a JSON block like this:
{
"mcpServers": {
"notes": {
"command": "npx",
"args": ["-y", "sample-notes-mcp-server", "/absolute/path/to/notes.json"]
}
}
}The trailing path argument is optional — omit it to use ./notes.json relative to the client's working directory. Using an absolute path is recommended so your notes land in a predictable place.
Claude Desktop
Add the block above to claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Then restart Claude Desktop.
Claude Code
claude mcp add notes -- npx -y sample-notes-mcp-server /absolute/path/to/notes.jsonDevelopment
npm install # install dependencies
npm run build # compile TypeScript to dist/
npm run start # run the built server
npm run smoke-test # spawn the built server via a real MCP stdio client and exercise every toolThe build uses a two-config split: tsconfig.json drives the editor and typecheck (and covers the smoke test), while tsconfig.build.json excludes the smoke test so it never ships in dist/.
License
MIT — see LICENSE.
Available Tools
4 toolsadd_noteA
Save a short text note for later. Returns the new note's id.
Inputs: text (required).
delete_noteA
Delete a saved note by its id.
Inputs: id (required).
list_notesB
List all saved notes.
Inputs: no named parameters.
search_notesA
Find saved notes containing the given text (case-insensitive).
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose (add, list, search, delete) with no overlap.
All tool names follow a consistent verb_noun pattern (add_note, list_notes, search_notes, delete_note).
4 tools is well-scoped for a simple notes application, covering core operations without excess.
Basic CRUD is covered except update; search provides an alternative to get-by-id. Minor gap.
Maintenance
Related MCP Connectors
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
An MCP server that used to create notes
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA simple MCP server for creating and managing notes with support for summarization functionality.1-
- FlicenseNot gradedqualityNot gradedmaintenanceA simple MCP server that implements a note storage system allowing users to add and summarize notes with customizable detail levels.3-
- FlicenseNot gradedqualityDmaintenanceA minimal MCP server for persistent note-taking, enabling create, update, delete, and search of notes with tags, plus resource-based retrieval of all notes or by title.-
- FlicenseNot gradedqualityDmaintenanceLightweight MCP server for adding, reading, and summarizing sticky notes persisted in a local file.1-