Skip to main content
Glama

mcp-server-sample — Servidor MCP mínimo para guardar y buscar notas

Es un servidor MCP mínimo que solo guarda y busca notas. No se conecta a ningún sistema externo. El almacenamiento es un único archivo notes.json en la misma carpeta.

Incluye los tres primitivos de MCP, uno de cada uno.

Primitivo

Quién lo decide

Contenido en este servidor

Tools

Lo decide el modelo

add_note (añadir nota) / search_notes (buscar notas)

Resources

La aplicación de IA lo obtiene y lo pasa

notes://all (todas las notas guardadas)

Prompts

El usuario lo selecciona explícitamente

weekly_review (revisión semanal)

Requisitos

  • Node.js 24 o superior (LTS. Verificar con node --version)

  • git

Related MCP server: mcp-snippetbox

Configuración

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

Si npm install se ejecuta correctamente, la configuración está lista. En este punto no se inicia. El servidor MCP lo inicia la aplicación de IA, por lo que no es necesario ejecutarlo desde la terminal.

Conectar a la aplicación de IA

Claude Code

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

Si claude mcp list muestra ✔ Connected, está conectado.

Claude Desktop

Ve a Configuración → Developer → «Edit Config» para abrir claude_desktop_config.json y añade lo siguiente.

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

Después de guardar, cierra completamente Claude Desktop y vuelve a iniciarlo (cerrar la ventana no es suficiente).

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

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

Verificación de funcionamiento

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

Se crea notes.json y se puede ver cómo su contenido aumenta.

Cambiar la ubicación de almacenamiento

Pasando una ruta absoluta a la variable de entorno NOTES_FILE, se puede cambiar la ubicación de almacenamiento.

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

Cuando no se conecta

Primero revisa los registros (logs). La causa suele aparecer allí.

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

Comprueba si después de Server started and connected successfully hay algún error.

Lo que aparece en el registro

Causa

Solución

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

La ruta de args es incorrecta

Ejecuta pwd en la raíz del repositorio y pega esa salida + /index.js

spawn node ENOENT

La aplicación de IA no encuentra node. Ocurre cuando PATH solo está configurado en el shell (nvm/volta, etc.)

Escribe la salida de which node (ruta absoluta) directamente en command

Cannot find package '@modelcontextprotocol/server'

Las dependencias no están instaladas

Ejecuta npm ci en la raíz del repositorio

El registro está vacío o no se actualiza

La configuración no se ha cargado

Verifica la sintaxis del JSON (comas, paréntesis), cierra completamente Claude Desktop (⌘Q en macOS) y vuelve a iniciarlo

Para determinar si el problema está en el servidor o en la aplicación de IA, lo más rápido es probar directamente desde la 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

Si se devuelve un JSON que contiene add_note y search_notes, el servidor funciona correctamente. En ese caso, revisa la configuración de la aplicación de IA (ruta, formato JSON, reinicio).

Medidas de seguridad en la cadena de suministro

Se han incluido configuraciones en .npmrc para prevenir la suplantación de paquetes npm. Se aplican cada vez que se ejecuta npm install / npm ci.

Configuración

Qué hace

ignore-scripts=true

No ejecuta scripts del ciclo de vida (como postinstall) de los paquetes dependientes durante la instalación. Bloquea la ruta de ejecución inicial que usaría un paquete comprometido. npm start / npm run funcionan como siempre (solo los scripts pre/post no se ejecutan).

save-exact=true

npm install <pkg> escribe la versión exacta en package.json sin ^, fijándola completamente.

min-release-age=7

Solo instala versiones publicadas hace más de 7 días. npm convierte esto en before=<fecha de hace 7 días> para resolver dependencias.

Las dependencias están fijadas exactamente en package.json (@modelcontextprotocol/server es 2.0.0, zod es 4.4.3), y registradas en package-lock.json con hash integrity. Si quieres instalar exactamente como está en el lock, usa npm ci en lugar de npm install.

Al actualizar dependencias, hazlo una por una de forma intencionada.

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

Licencia

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