Apple Notes MCP

Servidor MCP para Apple Notes con búsqueda semántica y operaciones CRUD. Claude busca, lee, crea, actualiza y gestiona tus notas de Apple mediante lenguaje natural.

GitHub

Prueba este MCPPatrocinado

Documentación

apple-notes-mcp

Servidor MCP para Apple Notes con búsqueda semántica y operaciones CRUD. Claude busca, lee, crea, actualiza y gestiona tus notas de Apple Notes mediante lenguaje natural.

Características

Búsqueda por fragmentos - Las notas largas se dividen en fragmentos para una coincidencia precisa
Caché de consultas - Búsquedas repetidas 60 veces más rápidas
Grafo de conocimiento - Descubrimiento de etiquetas, enlaces y notas relacionadas
Búsqueda híbrida - Búsqueda vectorial + por palabras clave con fusión de rango recíproco
Búsqueda semántica - Encuentra notas por significado, no por palabras clave
CRUD completo - Crear, leer, actualizar, eliminar y mover notas
Indexación incremental - Re-embedding solo de notas modificadas
Trabajos de indexación en segundo plano - Indexación completa/incremental asíncrona con sondeo de progreso
Embedding dual - HuggingFace local o API de OpenRouter

Novedades en 1.9.0

Indexación de bibliotecas grandes - Fetch lee propiedades de notas en lotes masivos, por lo que indexar miles de notas se completa en lugar de estancarse
Fetch resiliente - Las notas bloqueadas o en sincronización se reintentan por lote y se omiten con un informe en lugar de fallar la ejecución
Lecturas cancelables - Las lecturas largas de Notes tienen tiempo de espera (JXA_TIMEOUT_MS) y la cancelación realmente detiene el fetch

Novedades en 1.8.1

Filtrado de carpetas list-notes más rápido - list-notes ahora consulta solo la carpeta solicitada en lugar de escanear todas las notas primero
Corrección de nombres de carpetas duplicados - El filtrado de carpetas ahora agrega carpetas coincidentes entre cuentas
Rendimiento en bibliotecas grandes - El listado con ámbito de carpeta es significativamente más rápido en bibliotecas de notas grandes

Instalación

npm (recomendado)

npm install -g @disco_trooper/apple-notes-mcp
apple-notes-mcp

El asistente de configuración te guía a través de:

Elegir tu proveedor de embedding (local u OpenRouter)
Configurar claves API si es necesario
Configurar la integración con Claude Code
Indexar tus notas

Desde el código fuente

git clone https://github.com/disco-trooper/apple-notes-mcp.git
cd apple-notes-mcp
bun install
bun run start

Requisitos

macOS (usa Apple Notes mediante JXA)
Entorno de ejecución Bun
Aplicación Apple Notes con notas

Inicio rápido

Ejecuta el comando después de la instalación:

apple-notes-mcp

El asistente de configuración se inicia automáticamente en la primera ejecución. Reinicia Claude Code después de la configuración para usar las herramientas MCP.

Configuración

Configuración almacenada en ~/.apple-notes-mcp/.env:

Variable	Descripción	Predeterminado
`OPENROUTER_API_KEY`	Clave API de OpenRouter (habilita embeddings en la nube)	-
`EMBEDDING_MODEL`	Nombre del modelo (local u OpenRouter)	`Xenova/multilingual-e5-small`
`EMBEDDING_DIMS`	Dimensiones del embedding	`4096`
`READONLY_MODE`	Bloquear todas las operaciones de escritura	`false`
`INDEX_TTL`	Intervalo de auto-refresco en búsqueda en segundos (deshabilitado si no se establece)	-
`SEARCH_REFRESH_TIMEOUT_MS`	Tiempo máximo que la búsqueda espera el refresco antes de usar el índice obsoleto	`2000`
`INDEX_JOB_RETENTION_SECONDS`	Cuánto tiempo los trabajos de indexación completados/fallidos permanecen consultables	`3600`
`EMBEDDING_BATCH_SIZE`	Tamaño de lote para la generación de embeddings	`50`
`NOTES_FETCH_BATCH_SIZE`	Tamaño de lote para el fetch de Notes	`100`
`JXA_TIMEOUT_MS`	Tiempo máximo para una sola lectura de Notes en milisegundos	`120000`
`DEBUG`	Habilitar registro de depuración	`false`

Política de auto-refresco de búsqueda

search-notes no fuerza el refresco en cada solicitud.
Si INDEX_TTL no está establecido, el auto-refresco está deshabilitado y la búsqueda usa el índice actual.
Si INDEX_TTL está establecido, el refresco se ejecuta solo después de la expiración del TTL.
Si el refresco falla o tarda más que SEARCH_REFRESH_TIMEOUT_MS, la búsqueda recurre a resultados del índice obsoleto en lugar de agotar el tiempo de espera.

Para reconfigurar:

apple-notes-mcp setup
# or from source:
bun run setup

Proveedores de embedding

Local (predeterminado): Usa HuggingFace Transformers con Xenova/multilingual-e5-small. Gratuito, se ejecuta localmente, descarga de ~200MB.

OpenRouter: Usa API en la nube. Rápido, no requiere recursos locales, necesita clave API de openrouter.ai.

Consulta docs/models.md para comparar modelos.

Herramientas

Búsqueda y descubrimiento

`search-notes`

Búsqueda híbrida vectorial + texto completo.

query: "meeting notes from last week"
folder: "Work"           # optional, filter by folder
limit: 10                # default: 20
mode: "hybrid"           # hybrid, keyword, or semantic
include_content: false   # include full content vs preview

`list-notes`

Lista notas con ordenación y filtrado. Sin parámetros, muestra estadísticas del índice.

sort_by: "modified"      # created, modified, or title (default: modified)
order: "desc"            # asc or desc (default: desc)
limit: 10                # max notes to return (1-100)
folder: "Work"           # filter by folder (case-insensitive)

Cuando se proporciona folder, el servidor obtiene solo las carpetas coincidentes de Apple Notes. Esto mantiene rápidas las solicitudes con ámbito de carpeta incluso cuando tu biblioteca tiene cientos de notas.

Ejemplos:

Obtener las 5 notas más recientes: { sort_by: "created", order: "desc", limit: 5 }
Modificadas recientemente: { sort_by: "modified", limit: 10 }
Alfabéticamente en carpeta: { sort_by: "title", order: "asc", folder: "Projects" }

`list-folders`

Lista todas las carpetas de Apple Notes.

`get-note`

Obtiene el contenido de una nota por título.

title: "My Note"          # or "Work/My Note" for disambiguation
include_html: false       # include raw HTML (default: false)

`get-tables`

Extrae datos tabulares estructurados de una nota.

title: "My Note"

Devuelve:

{
  "tableCount": 2,
  "tables": [{
    "index": 0,
    "rows": [["Header1", "Header2"], ["Val1", "Val2"]],
    "formatting": [[{"bold": true}, {"bold": true}], ...]
  }]
}

Indexación

`index-notes`

Indexa notas para búsqueda semántica.

mode: "incremental"       # incremental (default) or full
force: false              # force reindex even if TTL hasn't expired
background: false         # optional; defaults to false (synchronous mode)

Usa mode: "full" para crear el índice de fragmentos para una mejor búsqueda en notas largas. La primera indexación completa tarda más porque genera fragmentos, pero las búsquedas posteriores son rápidas.

Para bibliotecas grandes, prefiere la indexación en segundo plano:

`start-index-job`

mode: "full"               # full or incremental

Devuelve una instantánea del trabajo con id, status y progress. Actualizaciones de progreso en pasos más pequeños en las fases de fetch, embedding y persistencia.

`get-index-job`

job_id: "<job-id>"

Consulta hasta que el estado sea completed, failed o cancelled. Puedes ver cancelling como estado transitorio.

`list-index-jobs`

limit: 10                  # optional, 1-50

`cancel-index-job`

job_id: "<job-id>"

Solicita cancelación de mejor esfuerzo para un trabajo en ejecución. La cancelación es cooperativa:

Un paso de larga duración debe alcanzar un punto de control de cancelación.
Puede quedar trabajo parcial.
Inicia un nuevo trabajo después de que el actual alcance cancelled.

`reindex-note`

Re-indexa una sola nota después de ediciones manuales.

title: "My Note"

Operaciones CRUD

`create-note`

Crea una nota en Apple Notes.

title: "New Note"
content: "# Heading\n\nMarkdown content..."
folder: "Work"            # optional, defaults to Notes

Después de crear, actualizar, eliminar o mover, el servidor sincroniza automáticamente los índices vectorial y de fragmentos en modo de mejor esfuerzo. Si la sincronización falla parcialmente, la respuesta de la herramienta incluye un index sync warning. Ejecuta reindex-note o index-notes.

`update-note`

Actualiza una nota existente.

title: "My Note"
content: "Updated markdown content..."
reindex: true             # re-embed after update (default: true)

`delete-note`

Elimina una nota (requiere confirmación).

title: "My Note"
confirm: true             # must be true to delete

`move-note`

Mueve una nota a otra carpeta.

title: "My Note"
folder: "Archive"

`batch-delete`

Elimina varias notas a la vez.

titles: ["Note 1", "Note 2"]  # OR folder: "Old Project"
confirm: true                 # required for safety

`batch-move`

Mueve varias notas a una carpeta de destino.

titles: ["Note 1", "Note 2"]  # OR sourceFolder: "Old"
targetFolder: "Archive"       # required

Gestión del índice

`purge-index`

Limpia todos los datos indexados. Úsalo al cambiar de modelo de embedding o para corregir un índice corrupto.

confirm: true   # required for safety

Después de purgar, ejecuta index-notes para reconstruir.

Grafo de conocimiento

`list-tags`

Lista todas las etiquetas con conteos de ocurrencia.

`search-by-tag`

Encuentra notas con una etiqueta específica.

tag: "project"
folder: "Work"    # optional
limit: 20         # default: 20

`related-notes`

Encuentra notas relacionadas con una nota fuente.

title: "My Note"
types: ["tag", "link", "similar"]  # default: all
limit: 10                          # default: 10

`export-graph`

Exporta el grafo de conocimiento para visualización.

format: "json"     # json or graphml
folder: "Work"     # optional filter

Formatos admitidos:

json - Para visualización personalizada (D3.js, aplicaciones web)
graphml - Para herramientas profesionales (Gephi, yEd, Cytoscape)

Configuración de Claude Code

Automática (recomendada)

El asistente de configuración agrega automáticamente apple-notes-mcp a Claude Code. Ejecuta apple-notes-mcp después de la instalación.

Manual

Agrega a ~/.claude.json:

Para instalación con npm:

{
  "mcpServers": {
    "apple-notes": {
      "command": "apple-notes-mcp",
      "args": [],
      "env": {}
    }
  }
}

Para instalación desde el código fuente:

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

Ejemplos de uso

Después de la configuración, usa lenguaje natural con Claude:

"Busca en mis notas ideas para proyectos"
"Crea una nota llamada 'Notas de reunión' en la carpeta Trabajo"
"¿Qué hay en mi nota sobre planes de vacaciones?"
"Mueve la nota 'Proyecto antiguo' a Archivo"
"Indexa mis notas" (después de agregar notas en Apple Notes)

Solución de problemas

"Nota no encontrada"

Usa el formato de ruta completa Folder/Note Title cuando varias notas compartan el mismo nombre.

Primera búsqueda lenta

Los embeddings locales descargan el modelo en el primer uso (~200MB). Las búsquedas posteriores son rápidas.

"READONLY_MODE está habilitado"

Establece READONLY_MODE=false en .env para habilitar operaciones de escritura.

Notas faltantes en la búsqueda

Ejecuta index-notes para actualizar el índice de búsqueda. Usa mode: full si el incremental no detecta cambios.

"Cuenta de iCloud no disponible" / `Can't get account "iCloud"`

Este error proviene de una implementación diferente de Apple Notes MCP que usa la herramienta search_notes y el argumento Keywords.

Este proyecto usa:

herramienta: search-notes
argumento: query

Si tu cliente llama a search_notes con Keywords, apunta tu configuración MCP a apple-notes-mcp y reinicia el cliente.

Errores de JXA

Asegúrate de que Apple Notes se ejecute y contenga notas. Otorga permisos de automatización cuando se soliciten.

"Error de análisis JSON: identificador inesperado undefined"

Esto generalmente significa que el proceso de indexación se quedó sin memoria. Intenta:

Cierra otras aplicaciones para liberar memoria
Establece EMBEDDING_BATCH_SIZE=25 en .env para reducir el uso de memoria
Reinicia la aplicación Apple Notes
Ejecuta index-notes nuevamente

Notas omitidas durante la indexación

Algunas notas pueden omitirse si están:

Bloqueadas - Desbloquéalas en Apple Notes si quieres que se indexen
En sincronización - Espera a que se complete la sincronización de iCloud y luego reindexa
Corruptas - Intenta copiar el contenido a una nota nueva y eliminar la antigua

El indexador informará qué notas se omitieron y continuará con el resto.

Desarrollo

# Type check
bun run check

# Run tests
bun run test

# Run with coverage
bun run test:coverage

# Run with debug logging
DEBUG=true bun run start

# Watch mode
bun run dev

Contribuciones

¡Se aceptan PRs! Por favor:

Ejecuta bun run check antes de enviar
Agrega pruebas para nuevas funcionalidades
Actualiza la documentación según sea necesario

Licencia

MIT