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

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

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

필요 사항

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

• git

설정

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 이후에 오류가 이어지지 않는지 확인하세요.

서버 측인지 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 할 때마다 적용됩니다.

의존성은 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