mcp-apple-notes

MCP Apple Notes

Un servidor Model Context Protocol (MCP) que permite búsqueda semántica y RAG (Retrieval Augmented Generation) sobre tus Apple Notes. Funciona con cualquier cliente compatible con MCP — Claude Desktop, Cursor, Windsurf, Cline y otros.

Características

• 🔍 Búsqueda semántica sobre Apple Notes usando el modelo de incrustaciones en el dispositivo all-MiniLM-L6-v2
• 📝 Capacidades de búsqueda de texto completo
• 📂 Soporte de carpetas — listar carpetas, navegar por carpeta, filtrar búsqueda por carpeta
• 📊 Almacenamiento vectorial usando LanceDB
• 🤖 Funciona con cualquier cliente compatible con MCP (Claude, Cursor, Windsurf, Cline, etc.)
• 🍎 Integración nativa con Apple Notes mediante JXA
• 🔒 Modo de solo lectura opcional para exploración segura
• 🏃‍♂️ Ejecución completamente local — no se necesitan claves API

Seguridad y Transparencia

Debido a que este servidor interactúa con tus notas privadas de Apple Notes, está diseñado con total transparencia en mente. Se ejecuta 100% localmente en tu Mac.

• Sin nube, sin telemetría — Sin claves API, sin que los datos salgan de tu máquina.
• JXA nativo de Apple — Usa el puente de scripting oficial de Apple JavaScript for Automation.
• Incrustaciones en el dispositivo — El modelo all-MiniLM-L6-v2 se ejecuta localmente mediante @huggingface/transformers.
• Verificable — Te animamos encarecidamente a leer cada línea de código (especialmente index.ts) antes de que toque tus notas.
• Los lanzamientos de GitHub incluyen sumas de verificación SHA-256 para que puedas verificar los artefactos descargados.

Instalación y Configuración

Elige el método de instalación que se adapte a tu flujo de trabajo.

Método 1: Instalar desde el código fuente (recomendado)

Al clonar el repositorio localmente, puedes inspeccionar el código fuente y saber exactamente qué se está ejecutando en tu máquina.

Requisitos previos: Node.js (v18+) o Bun

git clone https://github.com/Dan8Oren/mcp-apple-notes && cd mcp-apple-notes && bun install

{
  "mcpServers": {
    "apple-notes": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-apple-notes/index.ts"]
    }
  }
}

Usando NPM:

git clone https://github.com/Dan8Oren/mcp-apple-notes && cd mcp-apple-notes && npm install

Luego agrega el servidor a la configuración de tu cliente MCP. Reemplaza /path/to/mcp-apple-notes con la ubicación donde clonaste el repositorio:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-apple-notes/index.ts"]
    }
  }
}

Consejo: ¿Quieres probarlo sin riesgo? Habilita el modo de solo lectura para bloquear todas las operaciones de escritura mientras exploras.
"env": { "MCP_APPLE_NOTES_READ_ONLY": "1" }

Método 2: Inicio rápido mediante npx

Si prefieres un enfoque sin configuración y confías en el paquete npm publicado, puedes simplemente agregar esto directamente a tu configuración de MCP:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"]
    }
  }
}

Después de la configuración, reinicia tu cliente y pide a tu asistente de IA que "indexe mis notas" para comenzar.

Instrucciones por cliente

tail -n 50 -f ~/Library/Logs/Claude/mcp-server-apple-notes.log

# npm version:
claude mcp add apple-notes npx -- -y @dan8oren/mcp-apple-notes
# or from source:
claude mcp add apple-notes npx -- tsx /path/to/mcp-apple-notes/index.ts

Herramientas Disponibles

Verifica Antes de Confiar

Cada operación de Apple Notes es una llamada JXA que puedes inspeccionar en index.ts. Sin solicitudes de red, sin sincronización en segundo plano — solo llamadas locales al puente de scripting.

Modo de solo lectura

¿Quieres una red de seguridad? Habilita el modo de solo lectura para bloquear todas las operaciones de escritura — solo estarán disponibles las herramientas de búsqueda, listado y lectura:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"],
      "env": { "MCP_APPLE_NOTES_READ_ONLY": "1" }
    }
  }
}

Cuando está habilitado, solo estas herramientas están disponibles: index-notes, list-folders, list-notes, search-notes, get-note.

Modo verboso

Habilita el registro verboso para ver cada llamada JXA antes de que se ejecute (registrado en stderr):

Indicador CLI — agrega --verbose a los argumentos de configuración de tu cliente MCP:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["--verbose", "-y", "@dan8oren/mcp-apple-notes"]
    }
  }
}

Variable de entorno — para clientes que soportan env:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"],
      "env": { "MCP_APPLE_NOTES_VERBOSE": "1" }
    }
  }
}

Referencia de operaciones JXA

Todas las operaciones pasan por el puente de scripting JXA de Apple (Application('Notes')). Sin acceso directo al sistema de archivos, sin llamadas de red. La operación delete no es permanente — las notas van a Eliminados recientemente y se pueden recuperar dentro de 30 días.

Forma de Respuesta

Las respuestas de las herramientas son objetos JSON en un sobre consistente:

• Éxito: { "ok": true, "data": ... }
• Error: { "ok": false, "error": { "type": "...", "message": "..." } }

La mayoría de las respuestas orientadas a notas ahora incluyen el id estable de Apple Notes para que los clientes puedan rastrear notas de manera segura a través de renombrados y movimientos.

Comunidad y Soporte

Informes de errores, ideas, preguntas y demostraciones tienen un lugar — por favor usa el canal que se ajuste:

• 🐛 ¿Encontraste un error? → Abre un problema
• 💡 ¿Tienes una idea de funcionalidad? → Inicia un hilo en Ideas
• ❓ ¿Necesitas ayuda con la configuración o integración? → Pregunta en Q&A
• 🛠 ¿Construiste algo genial con esto? → Comparte en Show and tell
• 📣 Mantente al tanto de las actualizaciones → Anuncios

Los PRs son bienvenidos. Para cambios no triviales, por favor abre un problema o discusión primero para que podamos alinearnos en la dirección antes de que inviertas tiempo.

Agradecimientos

Originalmente basado en RafalWilinski/mcp-apple-notes.