mcp-notes-server

mcp-notes-server

Un servidor Model Context Protocol (MCP) mínimo, gratuito y de código abierto en Python que le da a cualquier asistente de IA compatible con MCP un bloc de notas persistente: crea notas, listalas y búscalas — almacenadas en un archivo JSON local y simple que tú controlas.

Construido con el SDK oficial de Python mcp (FastMCP). Sin base de datos, sin nube, sin cuentas. Tus notas nunca salen de tu máquina.

Herramientas

Herramienta	Qué hace
create_note	Crea una nota con un título (obligatorio, ≤120 caracteres) y cuerpo (≤10,000 caracteres). Devuelve el registro guardado con id y marcas de tiempo.
list_notes	Lista las notas guardadas, de más reciente a más antigua (límite configurable, 1–500).
search_notes	Búsqueda de palabras clave sin distinción de mayúsculas/minúsculas en títulos y cuerpos.

Inicio rápido

git clone <this-repo-url>
cd mcp-notes-server
pip install -r requirements.txt
python server.py

El servidor habla MCP a través de stdio. Conéctalo desde cualquier host MCP — consulta los ejemplos de configuración a continuación y en examples/.

Claude Desktop

Agrega a tu claude_desktop_config.json (consulta examples/claude_desktop_config.example.json):

{
  "mcpServers": {
    "notes-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-notes-server/server.py"]
    }
  }
}

Host MCP genérico

Consulta examples/mcp-client-config.generic.json — el mismo patrón de comando/argumentos stdio funciona para la mayoría de los hosts.

Pruébalo

1. Conecta tu host MCP y pregunta: "Crea una nota titulada 'Lista de compras' con leche, huevos y café."
2. Pregunta: "Busca en mis notas huevos."
3. Abre notes.json (creado automáticamente junto a server.py) para ver el almacenamiento crudo — es solo JSON.

Cómo funciona

• Los ayudantes de almacenamiento cargan/guardan un único archivo notes.json; los guardados son atómicos (escribir a un archivo temporal, luego reemplazar).
• Cada herramienta valida su entrada (título obligatorio y con límite de longitud, cuerpo con límite de longitud, consulta de búsqueda obligatoria).
• Las funciones de las herramientas son funciones ordinarias de Python decoradas con @mcp.tool() — las anotaciones de tipo se convierten en los esquemas de entrada de las herramientas. Todo el servidor es un solo archivo legible (~150 líneas), pensado para copiarse y adaptarse.

Ejecuta la prueba de humo (no se necesita host MCP):

python tests/smoke_test.py

Verificado de extremo a extremo sobre el protocolo MCP real (stdio, SDK oficial v1.x) — herramientas listadas, nota creada, buscada y listada: consulta tests/mcp_e2e_test.py y ejecútalo tú mismo después de pip install -r requirements.txt. Ten en cuenta que los requisitos fijan mcp<2: el SDK 2.x renombró FastMCP, y este código apunta a la API v1.

Alcance y seguridad

• Solo local. Este servidor lee/escribe un archivo JSON en su propia carpeta. No hace llamadas de red y no tiene herramienta de borrado — por diseño, como patrón inicial.
• Trátalo como una base de aprendizaje/prototipado, no como un servicio de producción endurecido: sin autenticación (los servidores stdio son lanzados por tu host como tu usuario), sin bloqueo de concurrencia más allá del reemplazo atómico de archivos.

Obtén el paquete completo

Este servidor gratuito es uno de tres iniciadores en el paquete MCP Server Starter Templates — el paquete completo agrega un servidor de consulta SQLite de solo lectura (con una protección probada contra inyección SQL: validación solo-SELECT) y un esqueleto de servidor de resumen web, además de configuraciones de cliente para los tres, una lista de verificación de pruebas y notas de seguridad para llevar servidores MCP hacia producción.

→ MCP Server Starter Templates (y más herramientas de agentes de IA: kits de pruebas AgentProof, kits de evaluación LLM/RAG, conjuntos de datos verificados para agentes): bradray2.gumroad.com

Muestras gratuitas de los kits de pago viven en el repositorio complementario, ai-agent-tools-free-samples.

Licencia

MIT — consulta LICENSE. Úsalo, hazle fork, publícalo.

Copyright (c) 2026 Brad Lucas.