Skip to main content
Glama

mcp-server-sample — 메모를 저장·검색하는 최소의 MCP 서버

메모를 저장하고 검색하는 것만 가능한 최소의 MCP 서버입니다. 외부 시스템에는 전혀 연결하지 않습니다. 저장 위치는 같은 폴더의 notes.json 하나의 파일뿐입니다.

MCP의 3가지 프리미티브를 각각 하나씩 갖추고 있습니다.

프리미티브

누가 결정하는가

이 서버에서의 내용

Tools

모델이 판단한다

add_note (메모 추가)/search_notes (메모 검색)

Resources

AI 앱이 획득하여 전달한다

notes://all (저장된 메모 전)

Prompts

사욕자가 명시적으로 선택한다

weekly_review (이번 주 회고)

필요 사항

  • Node.js 24 이상 (LTS. node --version으로 확인)

  • git

Related MCP server: mcp-snippetbox

설정

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

npm install이 통과되면 준비 완료입니다. 이 시점에서는 시작하지 않습니다. MCP 서버는 AI 앱이 시작하기 때문에, 직접 터미널에서 실행할 필요가 없습니다.

AI 앱에 연결

Claude Code

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

claude mcp list에서 ✔ Connected가 나타나면 연결된 것입니다.

Claude Desktop

설정 → Developer → 「Edit Config」에서 claude_desktop_config.json을 열고 다음을 추가합니다.

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

저장한 후 Claude Desktop을 완전히 종료하고 다시 시작합니다 (창을 닫는 것만으로는 반영되지 않습니다).

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

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

작동 확인

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

notes.json이 만들어지고, 내용이 느어나는 것을 확인할 수 있습니다.

저장 위취 변경

환경 변수 NOTES_FILE에 절대 경로를 전달하면 저장 위취를 변경할 수 있습니다.

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

연결되지 않을 때

먼저 로그를 봅니다. 원인은 대개 여기에 나타납니다.

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

Server started and connected successfully 이후에 오류가 이어지지 않는지 확인하세요.

로그에 나타난 것

원인

대처

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

args의 경로가 다름

리포지토리 직하에서 pwd를 실행하고, 그 출력 + /index.js를 다시 붙여넣기

spawn node ENOENT

AI 앱에서 node를 찾을 수 없음. nvm/volta 등으로 PATH가 셸 설정에만 있는 경우 발생

which node의 출력(절대 경로)을 command에 그대로 기재

Cannot find package '@modelcontextprotocol/server'

의존성이 설치되지 않음

리포지토리 직하에서 npm ci

로그가 비었거나 갱신되지 않음

설저이 로드되지 않음

JSON 구문(표, 괄호)을 확인하고, Claude Desktop을 완전히 종료(macOS는 ⌘Q)한 후 다시 시작

서버 측인지 AI 앱 측인지의 구분은 로컬에서 직접 실행해보는 것이 밉릅니다.

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

add_note와 search_notes를 포함한 JSON이 반환되면 서버는 정상입니다. 그 경우 AI 앱 측의 설정(경로·JSON 작선법·재시작)을 의심하세요.

공급망 보안

npm 패키지 탈취를 가정한 설정을 .npmrc에 넣어 두었습니다. npm install / npm ci 할 때마다 적용됩니다.

설정

하는 일

ignore-scripts=true

설취 시 의존 패키지의 라이프사이클 스크립트(postinstall 등)를 실해하지 않음. 탈취된 패키지가 처음 사욕하는 실해 경로를 차단. npm start / npm run은 종래대로 동작(pre/post 스크립트만 실해되지 않음)

save-exact=true

npm install <pkg>가 package.json에 ^를 붙이지 않고, 완전 고정으로 작선

min-releae-age=7

공개로부터 7일이 지난 버전만 설취. npm은 이곳을 before=<7일 전의 일시>로 변환하여 의존을 해결

의존성은 package.json에서 완전 고정 (@modelcontextprotocol/server는 2.0.0, zod는 4.4.3), package-lock.json에 integrity 해시와 함께 기록되어 있습니다. lock대로 설치하려면 npm install이 아닌 npm ci를 사용하세요.

의존성을 갱신할 때는 의도적으로 하나씩 올립니다.

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

라이선스

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