mcp-server-sample
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 |
|
Resources | La aplicación de IA lo obtiene y lo pasa |
|
Prompts | El usuario lo selecciona explícitamente |
|
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 installSi 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.jsSi 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.jsonWindows:
%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.logComprueba si después de Server started and connected successfully hay algún error.
Lo que aparece en el registro | Causa | Solución |
| La ruta de | Ejecuta |
| La aplicación de IA no encuentra | Escribe la salida de |
| Las dependencias no están instaladas | Ejecuta |
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.jsSi 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 |
| No ejecuta scripts del ciclo de vida (como |
|
|
| Solo instala versiones publicadas hace más de 7 días. npm convierte esto en |
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 toolsadd_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
Scored across 2 tools
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.
Both tool names follow a consistent verb_noun pattern (add_note, search_notes) using lowercase with underscores. The naming is predictable and clear.
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.
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
Related MCP Connectors
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables adding, getting, and listing notes through MCP, with state persisted to a JSON file in the home directory.MIT
- AlicenseNot gradedqualityCmaintenanceEnables managing notes through a simple MCP server, providing tools to add, retrieve, update, delete, and list notes for use with Claude Desktop.MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI clients to create, list, and search notes stored in a local JSON file through the Model Context Protocol.-
- AlicenseNot gradedqualityCmaintenanceEnables Claude Desktop to add, retrieve, update, delete, and list notes persisted in a JSON file whose path is set via MCP_NOTES_FILE or --notes-file, with atomic, lock-protected saves.MIT