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-server

Or install it globally:

npm install -g sample-notes-mcp-server
sample-notes-mcp-server

Usage

sample-notes-mcp-server [notes-file]

• notes-file (optional) — path to the JSON file where notes are stored. Defaults to ./notes.json in 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
add_note	text: string	Save a short text note. Returns the new note's id.
list_notes	(none)	List all saved notes.
search_notes	query: string	Find notes containing query (case-insensitive substring match).
delete_note	id: number	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.json
• Windows: %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.json

Development

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 tool

The 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.