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.

Requisitos

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

• git

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.

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.

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