Amber Notes (ambernotes.app)

npx add-mcp 'https://mcp.ambernotes.app'

Amber Notes, la aplicación de notas para iPhone y Mac, tiene un servidor MCP remoto integrado. Esta página es para desarrolladores y para cualquier persona curiosa sobre cómo funciona: la dirección, cómo una aplicación de IA inicia sesión y obtiene aprobación, y cada herramienta que puede llamar.

Amber Notes preguntando "¿Permitir que ChatGPT use tus notas?" con una opción de Leer y Editar o Solo Lectura, y botones de Permitir y No Permitir.

La dirección

https://mcp.ambernotes.app

• Transporte: MCP Streamable HTTP, respondiendo con JSON. No hay flujo enviado por el servidor; los clientes publican cada solicitud.
• Versiones de protocolo: 2025-11-25, 2025-06-18, 2025-03-26 y 2024-11-05.
• Nombre del servidor: amber-notes. Envía instrucciones en initialize que le dicen al modelo cómo están organizadas las notas.

Cómo funciona el acceso

Hay dos formas de entrar. Ambas requieren una cuenta de Amber Notes, y ambas son aprobadas por la persona.

Iniciar sesión con OAuth (ChatGPT, Claude y otras aplicaciones)

1. Una solicitud no autenticada recibe un 401 con un encabezado WWW-Authenticate que apunta a los metadatos del recurso protegido, en la dirección anterior más /.well-known/oauth-protected-resource.
2. El cliente se registra (registro dinámico de clientes) e inicia OAuth 2.1 con PKCE (S256). Los ámbitos son notes:read y notes:write.
3. Los metadatos del servidor de autorización están en la dirección anterior más /.well-known/oauth-authorization-server.
4. El paso de autorización abre ambernotes.app/connect. La persona inicia sesión allí (correo electrónico y contraseña, o Iniciar sesión con Apple), y la página muestra un número de dos dígitos. Amber Notes en su iPhone o Mac pregunta "¿Permitir que [aplicación] use tus notas?" y dónde va el acceso; escriben el número, eligen Leer y Editar o Solo Lectura, luego Permitir. Sin un dispositivo cercano, pueden aprobar en la página con su clave de recuperación.
5. El cliente obtiene un token de acceso (válido por una hora) y un token de actualización. Los tokens solo abren este servidor.

Token de acceso (Claude Code, Codex y scripts)

En Amber Notes, Configuración, Conectar una IA, Claude Code o Codex crea un token que comienza con pane_, de solo lectura o lectura y edición. Envíalo como Authorization: Bearer pane_…. La guía de Claude Code y Codex tiene la configuración exacta.

Configuración, Conectar una IA: configuración guiada para cada aplicación, y todo lo que está conectado.

Cada conexión aparece en Amber Notes bajo Conectado, y la persona puede desconectarla en cualquier momento. Cada llamada de herramienta se ejecuta como esa persona, con seguridad a nivel de fila, por lo que un token solo puede llegar a las notas de su propietario. Las llamadas tienen límite de velocidad por cuenta.

Las notas están cifradas de extremo a extremo, por lo que el servidor no puede leerlas en reposo. Aprobar una conexión le da una copia de la clave de las notas, bloqueada con un secreto derivado de su propio token. Durante cada solicitud, el servidor desbloquea la clave en memoria, descifra lo que la llamada necesita y la elimina cuando la solicitud termina; desconectar elimina esa copia. Las notas bloqueadas permanecen fuera de alcance, ya que su clave proviene de la contraseña de las notas. Una aplicación de notas cifrada que ChatGPT y Claude pueden usar explica la compensación.

Qué sucede con los cambios

• Cada edición conserva la versión anterior. note_history las lista y restore_revision restaura una.
• En la aplicación, la persona ve lo que una IA cambió, con Deshacer.
• Las notas eliminadas van a Eliminados recientemente durante 30 días y se pueden restaurar con restore_note.
• Una conexión de solo lectura solo ve las herramientas marcadas como lecturas a continuación.

Herramientas

Las notas son markdown, y la primera línea es el título. Las listas de verificación son líneas - [ ], y las tablas son tablas markdown. Comienza con get_overview o search_notes, y lee una nota antes de editarla.

• get_overview (lecturas). Una vista general de las Amber Notes de la persona: carpetas con recuentos, notas fijadas y las notas editadas más recientemente.
• search_notes (lecturas). Búsqueda de texto completo en títulos y cuerpos. Devuelve notas clasificadas con un fragmento resaltado («coincidencia»). Las notas bloqueadas se omiten.
• list_notes (lecturas). Lista notas, de más reciente a más antigua, opcionalmente en una carpeta. Úsalo para navegar; usa search_notes para encontrar algo.
• read_note (lecturas). Devuelve el markdown de una nota con su carpeta, fechas, versión y esquema. Para notas largas, lee un rango de líneas; establece line_numbers para ver dónde están los encabezados.
• create_note (cambios). Crea una nota a partir de markdown. La primera línea se convierte en el título (escríbela como texto plano o '# Título').
• edit_note (cambios; puede eliminar o reemplazar). Ediciones precisas: cada old_text debe coincidir con la nota exactamente una vez (cópialo de read_note) y se reemplaza por new_text. Las ediciones se aplican en orden. Falla sin cambiar nada si una no coincide.
• append_to_note (cambios). Agrega markdown al final de una nota, o al final (o inicio) de la sección bajo un encabezado. Bueno para registros, listas y diarios.
• replace_note_body (cambios; puede eliminar o reemplazar). Reemplaza toda la nota con nuevo markdown. Úsalo solo para reescrituras completas; prefiere edit_note. La persona ve el cambio en Amber Notes con Deshacer, y la versión anterior permanece en el historial.
• set_checklist_item (cambios). Marca o desmarca una línea '- [ ] elemento', coincidiendo por su texto.
• move_note (cambios). Mueve una nota a otra carpeta, creando la carpeta si no existe. Usa una ruta como "Trabajo/Clientes" para anidar.
• pin_note (cambios). Fija una nota al principio de la lista, o la desfija. El estado fijado se muestra como pinned\ en cada listado de notas.
• delete_note (cambios; puede eliminar o reemplazar). Mueve una nota y sus sub-notas a Eliminados recientemente. Esto se puede deshacer: restore_note la trae de vuelta dentro de 30 días.
• restore_note (cambios). Trae una nota (y sus sub-notas) de vuelta desde Eliminados recientemente.
• list_folders (lecturas). Todas las carpetas como rutas tipo "Trabajo/Planificación Q4", con cuántas notas muestra cada una en la aplicación.
• create_folder (cambios). Crea una carpeta; usa una ruta como "Trabajo/Clientes" para anidarla.
• rename_folder (cambios). Renombra una carpeta en su lugar. Sus notas y sub-carpetas permanecen dentro.
• delete_folder (cambios; puede eliminar o reemplazar). Elimina una carpeta y sus sub-carpetas. Sus notas (y las sub-notas de esas notas) van a Eliminados recientemente, y cada una se puede recuperar con restore_note dentro de 30 días; las carpetas en sí no se restauran.
• note_history (lecturas). Versiones anteriores de una nota, de más reciente a más antigua, con quién la cambió (aplicación o cliente de IA).
• restore_revision (cambios; puede eliminar o reemplazar). Pone una versión anterior (de note_history) de vuelta como el cuerpo de la nota. El cuerpo actual también se conserva en el historial.
• create_sub_note (cambios). Crea una nota que vive dentro de otra nota: está enlazada desde la principal (una línea [Título](pane-note:id) agregada al final, o bajo un encabezado) y no aparece en la lista principal.
• list_files (lecturas). Archivos guardados en Amber Notes (PDF, hojas de cálculo, imágenes…), de más reciente a más antiguo, con las notas que los incrustan.
• get_file (lecturas). Los detalles de un archivo y su contenido: archivos de texto (CSV, JSON, markdown…) como texto, imágenes como imagen, PDF y otros archivos como recurso adjunto. Los archivos de más de 8 MB solo se pueden abrir en Amber Notes.
• read_table (lecturas). Lee una tabla en una nota: sus columnas (con tipos y valores permitidos para rastreadores) y sus filas como objetos. Úsalo antes de registrar para usar los nombres de columna y valores correctos.
• log_table_row (cambios; puede eliminar o reemplazar). Agrega una fila a una tabla. En un rastreador con una columna de fecha, actualiza la fila de esa fecha si existe (la fecha por defecto es hoy). Los valores se verifican contra el tipo de cada columna: las escalas deben estar en rango, las opciones una de las opciones, Sí/No también acepta verdadero/falso.
• delete_table_row (cambios; puede eliminar o reemplazar). Elimina la fila para una fecha (rastreadores) o en un índice de fila basado en 0 de una tabla.
• search (lecturas). Busca en las Amber Notes de la persona por palabras o frases. Devuelve ids y títulos de notas; lee una con fetch. Las notas bloqueadas se omiten.
• fetch (lecturas). Obtiene una nota de Amber Notes por id (de la búsqueda) como su markdown completo, con carpeta, estado fijado y hora de última edición.

search y fetch siguen la forma que ChatGPT espera para buscar y leer. Cada herramienta lleva anotaciones MCP (readOnlyHint, y destructiveHint donde corresponde), para que los clientes puedan preguntar antes de un cambio.

Instalar en tu herramienta de IA

Cada una de estas agrega la dirección anterior. La primera vez que la herramienta se conecta, tu navegador abre ambernotes.app/connect: inicia sesión allí, luego aprueba en tu iPhone o Mac escribiendo el número que muestra la página, y elige Leer y Editar o Solo Lectura. Necesitas la aplicación gratuita y una cuenta.

Claude Code

claude plugin marketplace add emilwagman/amber-notes
claude plugin install amber-notes

El plugin agrega el servidor y una habilidad que le dice a Claude cómo están organizadas tus notas. Luego ejecuta /mcp en Claude Code, elige amber-notes e inicia sesión.

O agrega solo el servidor, para cada proyecto:

claude mcp add --scope user --transport http amber-notes https://mcp.ambernotes.app

Codex

codex mcp add amber_notes --url https://mcp.ambernotes.app

Codex inicia el inicio de sesión de inmediato. Para iniciar sesión de nuevo más tarde, ejecuta codex mcp login amber_notes.

Gemini CLI

gemini extensions install https://github.com/emilwagman/amber-notes

Luego ejecuta /mcp auth amber-notes en Gemini CLI para iniciar sesión.

VS Code

code --add-mcp '{"name":"amber-notes","type":"http","url":"https://mcp.ambernotes.app"}'

La primera vez que VS Code inicia el servidor, te pide iniciar sesión.

Incredible

1. Abre Apps y busca Amber Notes.
2. Elige Conectar, luego Permitir en Amber Notes.
3. De vuelta en Incredible, elige Vamos.

Amber Notes lo muestra como una aplicación en esta computadora que se llama a sí misma "incredible", comenzando en Solo Lectura. En una versión anterior de Incredible, elige Agregar aquí en la parte inferior de Apps (o Agregar otro servidor MCP), pega https://mcp.ambernotes.app, luego Continuar e Iniciar sesión, y Agregar servidor después de permitirlo.

Con un token en lugar de iniciar sesión

Cualquiera de estas herramientas puede usar un token de acceso en su lugar. En Amber Notes, abre Configuración, Conectar una IA, Codex, y elige Crear token de acceso. El token funciona en cualquier cliente MCP; envíalo como un encabezado Authorization: Bearer pane_…, como muestra la guía de Claude Code y Codex. Se muestra una sola vez, así que mantenlo privado.

Conéctalo

• Conecta ChatGPT o Claude a tus notas: agrega la dirección como una aplicación personalizada o conector.
• Usa tus notas desde Claude Code y Codex: un comando, o unas pocas líneas de configuración.
• Gemini CLI, VS Code e Incredible: los pasos para cada uno están arriba.
• Cualquier otra cosa que hable MCP: agrega la dirección e inicia sesión cuando lo pida.

¿Eligiendo una aplicación de notas para un agente? La mejor aplicación de notas para agentes de IA establece los criterios. ¿Vienes de Apple Notes? Servidores MCP de Apple Notes comparados cubre los servidores locales para Notes en una Mac, y cómo difieren de este. Servidores MCP de Obsidian comparados hace lo mismo para bóvedas de Obsidian.

El servidor es de código abierto. Léelo en supabase/functions/mcp en GitHub.

Verificado contra la aplicación en .