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.

Requirements

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

• git

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.

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.

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