Skip to main content
Glama
sample-notes-mcp-server

sample-notes-mcp-server

by hanoak

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

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

Available Tools

4 tools
add_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

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose (add, list, search, delete) with no overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (add_note, list_notes, search_notes, delete_note).

    Tool Count5/5

    4 tools is well-scoped for a simple notes application, covering core operations without excess.

    Completeness4/5

    Basic CRUD is covered except update; search provides an alternative to get-by-id. Minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers