Skip to main content
Glama

mcp-server-sample — Minimal MCP Server for Saving and Searching Notes

A minimal MCP server that only saves and searches notes. It does not connect to any external systems. The only storage is a single notes.json file in the same folder.

It includes one of each of the three MCP primitives.

Primitive

Decided by

Contents in this server

Tools

Model decides

add_note (add a note) / search_notes (search notes)

Resources

AI app fetches and passes

notes://all (all saved notes)

Prompts

User explicitly selects

weekly_review (weekly review)

Requirements

  • Node.js 24 or higher (LTS. Check with node --version)

  • git

Related MCP server: mcp-snippetbox

Setup

git clone https://github.com/utakatano/mcp-server-sample.git
cd mcp-server-sample
npm install

Once npm install completes successfully, you are ready. Do not start it at this point. The MCP server is started by the AI app, so you do not need to run it manually from the terminal.

Connect to the AI App

Claude Code

claude mcp add notes -- node /絶対パス/mcp-server-sample/index.js

If claude mcp list shows ✔ Connected, it is connected.

Claude Desktop

Go to Settings → Developer → "Edit Config" to open claude_desktop_config.json and add the following.

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/絶対パス/mcp-server-sample/index.js"]
    }
  }
}

After saving, fully quit Claude Desktop and restart it (closing the window alone is not enough).

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Verification

「来週までにネットワーク構成を確認する」とメモして
「ネットワーク」を含むメモを探して

You can confirm that notes.json is created and its contents increase.

Changing the Storage Location

Pass an absolute path to the environment variable NOTES_FILE to change the storage location.

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/絶対パス/mcp-server-sample/index.js"],
      "env": { "NOTES_FILE": "/絶対パス/my-notes.json" }
    }
  }
}

When It Does Not Connect

First, check the log. The cause is usually there.

tail -20 ~/Library/Logs/Claude/mcp-server-notes.log   # macOS
# Windows: %APPDATA%\Claude\logs\mcp-server-notes.log

Look to see if there are any errors after Server started and connected successfully.

What appears in the log

Cause

Remedy

Cannot find module '/.../index.js'

The path in args is wrong

Run pwd in the repository root and paste its output + /index.js

spawn node ENOENT

The AI app cannot find node. Occurs when PATH is only in the shell config (e.g., nvm / volta)

Write the output of which node (absolute path) directly into command

Cannot find package '@modelcontextprotocol/server'

Dependencies are not installed

Run npm ci in the repository root

Log is empty or not updating

The configuration is not loaded

Check JSON syntax (commas, brackets) and fully quit Claude Desktop (macOS: ⌘Q) before restarting

To determine whether the issue is on the server side or the AI app side, it is fastest to run the server directly from your terminal.

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}\n' \
  | node /絶対パス/mcp-server-sample/index.js

If a JSON containing add_note and search_notes is returned, the server is working correctly. In that case, suspect the AI app's configuration (path, JSON formatting, restart).

Supply Chain Countermeasures

Settings to guard against npm package hijacking are included in .npmrc. They take effect every time npm install / npm ci is run.

Setting

What it does

ignore-scripts=true

Does not execute lifecycle scripts (e.g., postinstall) of dependency packages during installation. Blocks the first execution path a hijacked package would use. npm start / npm run still work as usual (only pre/post scripts are disabled)

save-exact=true

npm install <pkg> writes exact versions to package.json without ^

min-release-age=7

Only installs versions published more than 7 days ago. npm converts this to before=<date 7 days ago> when resolving dependencies

Dependencies are fully pinned in package.json (@modelcontextprotocol/server is 2.0.0, zod is 4.4.3), and recorded with integrity hashes in package-lock.json. To install exactly as specified in the lock file, use npm ci instead of npm install.

When updating dependencies, upgrade them one at a time intentionally.

npm outdated
npm install @modelcontextprotocol/server@2.1.0   # save-exact により完全固定で書かれる
npm ls --all                                      # 増えた依存を目で確認する

License

MIT

Available Tools

2 tools
add_noteメモを追加するA

メモを1件保存する。打ち合わせの決定事項や、あとで思い出したいことを記録するときに使う。

Inputs: text (required), tags.

search_notesメモを検索するB

保存済みのメモをキーワードで検索する。本文とタグの両方を対象にする。

Inputs: keyword (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have completely distinct purposes: one creates/ stores a note, the other retrieves notes via search. There is no overlap or ambiguity between writing and searching.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern (add_note, search_notes) using lowercase with underscores. The naming is predictable and clear.

    Tool Count3/5

    With only 2 tools, the set feels minimal. While the tools cover basic create and read/search operations, the server's purpose (saving and retrieving notes) could reasonably include more tools (e.g., update, delete, list tags) to avoid being overly thin.

    Completeness2/5

    The domain is a personal note-taking system, but only add and search operations are provided. Missing critical operations like update, delete, and get all notes (without search) create significant gaps that would frustrate or block a typical agent workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers