Servidor MCP de reMarkable

Accede a una biblioteca de reMarkable desde clientes MCP como Claude, VS Code Copilot, OpenWebUI y otras herramientas compatibles.

Características

• Navega por carpetas y documentos recientes.

• Busca nombres, etiquetas y texto extraído.

• Lee texto mecanografiado, texto de PDF y EPUB, resaltados y anotaciones.

• Renderiza cuadernos y PDF anotados como PNG o SVG.

• Exporta un documento como un recurso PDF completo o Markdown por secciones.

• Ejecuta OCR de escritura a mano mediante Google Vision o Tesseract.

• Sube archivos y gestiona carpetas en transportes compatibles.

• Renderiza Markdown como PDF y súbelo a la tableta.

• Abre un lienzo interactivo en clientes que admiten MCP Apps.

• Sirve MCP sobre stdio o Streamable HTTP local.

• Sirve MCP 2026-07-28 y todas las revisiones anteriores compatibles con el SDK desde un único MCPServer estable del SDK 2.x.

Related MCP server: reMarkable MCP Server

Instalación rápida

Requisito previo: instalar uv

Los comandos siguientes usan uvx, que se incluye con uv. Las imágenes de página se rasterizan con PyMuPDF; no es necesario instalar Cairo, navegador ni ningún runtime gráfico en macOS, Linux o Windows.

macOS y Linux

Usa el instalador independiente oficial:

curl -LsSf https://astral.sh/uv/install.sh | sh

O instala con Homebrew:

brew install uv

Windows

Usa el instalador independiente oficial desde PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

O instala con WinGet:

winget install --id=astral-sh.uv -e

Elige una conexión

Empieza con el primer modo que se ajuste a tu configuración.

Interfaz web USB

Conecta por USB y habilita la interfaz web en los Ajustes de almacenamiento de tu tableta.

1. Conecta tu reMarkable por USB

2. En tu tableta, abre Ajustes > Almacenamiento y habilita Interfaz web USB

3. Instala mediante el botón de arriba

Añade a .vscode/mcp.json:

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--usb"],
      "env": {
        "GOOGLE_VISION_API_KEY": "your-api-key"
      }
    }
  }
}

• Asegúrate de que tu reMarkable esté conectado por USB y desbloqueado

• Verifica que la interfaz web USB esté habilitada en Ajustes > Almacenamiento

• La tableta debería ser accesible en http://10.11.99.1

Modo de directorio local

Lee la carpeta de sincronización de la app de escritorio oficial de reMarkable desde el disco. Este modo es sin conexión y de solo lectura. La app de escritorio controla la sincronización.

Añade a .vscode/mcp.json:

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--local-dir"]
    }
  }
}

Sin ruta, la carpeta de datos de la app de escritorio se detecta automáticamente:

• macOS (app actual): ~/Library/Containers/com.remarkable.desktop/Data/Library/Application Support/remarkable/desktop

• macOS (app heredada): ~/Library/Application Support/remarkable/desktop

• Windows: %APPDATA%\remarkable\desktop

• Linux: ~/.local/share/remarkable/desktop

O apunta a cualquier directorio de estilo xochitl (por ejemplo, una copia de seguridad de la tableta):

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--local-dir", "/path/to/xochitl-data"]
    }
  }
}

• La frescura del contenido depende de la app de escritorio. Mantenla en ejecución y con sesión iniciada.

• Este modo es de solo lectura. Las escrituras directas podrían omitir la sincronización y corromper la caché de la app.

• Si no se puede encontrar el directorio y hay un token de nube configurado, el servidor recurre al modo nube para acceso de lectura (el servidor permanece de solo lectura porque se lanzó en modo de directorio local)

Modo nube

El modo nube funciona sin conexión de dispositivo y requiere una suscripción a reMarkable Connect.

Obtiene metadatos en paralelo y almacena en caché blobs direccionados por contenido en disco. Consulta Rendimiento y caché de nube para la configuración.

1. Obtén un código de un solo uso

Ve a my.remarkable.com/device/desktop/connect y genera un código.

2. Convierte a token

uvx remarkable-mcp --register YOUR_CODE

El registro guarda el token en ~/.rmapi. Cuando tu cliente MCP ejecuta el servidor como el mismo usuario en la misma máquina, remarkable-mcp lee ese archivo automáticamente, por lo que no necesitas poner un token en la configuración del cliente. Establece REMARKABLE_TOKEN solo cuando ~/.rmapi no esté disponible, como cuando el servidor se ejecuta bajo otro usuario o en otra máquina.

3. Configura tu cliente MCP

Definición mínima de servidor independiente del cliente

Añade esta definición de servidor usando la interfaz de configuración MCP o el envoltorio requerido por tu cliente:

{
  "command": "uvx",
  "args": ["remarkable-mcp"]
}

No se necesita una entrada env cuando el servidor puede leer el token desde ~/.rmapi.

VS Code

El .vscode/mcp.json de VS Code usa un objeto servers de nivel superior. La credencial guardada en ~/.rmapi significa que no se requiere entrada de token:

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp"]
    }
  }
}

Claude Desktop y otros clientes

Claude Desktop y muchos otros clientes MCP usan un objeto mcpServers de nivel superior y valores literales en env; no usan el array inputs de VS Code. Con el token disponible en ~/.rmapi, la configuración mínima es:

{
  "mcpServers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp"]
    }
  }
}

Si el archivo de token no está disponible, añade "env": {"REMARKABLE_TOKEN": "tu-token"} a la entrada del servidor remarkable. Consulta la documentación de tu cliente si usa una clave externa diferente o un mecanismo de almacenamiento de secretos.

Modo SSH

SSH proporciona acceso directo al sistema de archivos y autoría nativa de cuadernos. Requiere modo desarrollador, que restablece la tableta de fábrica al habilitarse. Usa este modo solo cuando USB web, directorio local o modo nube no proporcionen la operación que necesitas.

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--ssh"]
    }
  }
}

Consulta la guía de configuración de SSH para autenticación y configuración del dispositivo.

Modos de conexión

Todos los modos admiten lectura, renderizado y exportación de un solo documento. La nube y SSH admiten gestión completa de la biblioteca. USB web admite subida pero no acepta una carpeta de destino. El modo de directorio local es de solo lectura.

¹ Operaciones de carpeta = crear carpeta / mover / renombrar / eliminar. La subida y las operaciones de carpeta están habilitadas por defecto; pasa --read-only para exponer un servidor de solo lectura. Las eliminaciones mueven elementos a la papelera y solicitan confirmación cuando tu cliente admite elicitación, y se rechazan sin ella a menos que se establezca REMARKABLE_SKIP_CONFIRM=1.

² La app de escritorio en sí inicia sesión en la nube de reMarkable para sincronizar; el modo de directorio local solo lee lo que la app ya ha sincronizado en disco.

Recurso automático a la nube

Si un transporte de dispositivo seleccionado no está disponible y hay una credencial de nube configurada, el servidor recurre al modo nube. Un servidor lanzado con --local-dir permanece de solo lectura después del recurso. remarkable_status informa el transporte efectivo y establece fell_back_to_cloud.

Pasa --no-cloud-fallback (o establece REMARKABLE_DISABLE_CLOUD_FALLBACK=1) para deshabilitar esto y fallar en su lugar cuando el dispositivo no esté accesible.

El transporte se resuelve una vez por proceso de servidor. Reinicia el servidor MCP después de conectar un dispositivo o iniciar la app de escritorio si el proceso ya recurrió a la nube.

Configuración detallada:

• Configuración de USB web

• Configuración de SSH

• Rendimiento y caché de nube

OpenWebUI (Streamable HTTP)

La conexión MCP nativa de OpenWebUI usa Streamable HTTP. Inicia remarkable-mcp en la misma máquina:

uvx remarkable-mcp --http

Luego añade http://127.0.0.1:8000/mcp como URL del servidor MCP en OpenWebUI. El transporte HTTP se combina con --usb, --ssh y --read-only; por ejemplo:

uvx remarkable-mcp --usb --http

La dirección de enlace y el puerto también se pueden establecer con --host / --port o REMARKABLE_MCP_HOST / REMARKABLE_MCP_PORT.

El servidor usa el endpoint de doble era del SDK de Python MCP 2.x. Las solicitudes modernas 2026-07-28 no tienen sesión; los clientes más antiguos continúan usando el protocolo de inicio y las sesiones MCP heredadas en la misma ruta /mcp. El token de reMarkable y el transporte de tableta seleccionado permanecen como configuración local de CLI/env del proceso y nunca se infieren de los encabezados de autorización HTTP de MCP.

[!ADVERTENCIA] Streamable HTTP no tiene autenticación incorporada. Se enlaza a 127.0.0.1 por defecto. Mantén ese valor predeterminado a menos que controles el límite de red. Los enlaces comodín como 0.0.0.0 y :: se rechazan porque no pueden proporcionar una lista de hosts estricta. Una dirección concreta no loopback está permitida pero expone cada herramienta habilitada, incluidas las escrituras, a clientes que puedan alcanzar el puerto.

Acceso remoto a través de un proxy inverso autenticado

Mantén remarkable-mcp en su enlace de bucle local predeterminado y coloca el proxy en el mismo host. La protección contra reencuadre de DNS de MCPServer solo permite valores de Host y Origin de bucle local de forma predeterminada. Un proxy que reenvíe su nombre de host público sin cambios recibirá por tanto 421 Solicitud mal dirigida; un Origin de navegador público recibirá 403 Prohibido.

El proxy debe autenticar las solicitudes, reescribir Host al upstream de bucle local y limpiar Origin. Por ejemplo, con nginx y un archivo htpasswd existente:

location /mcp {
    auth_basic "reMarkable MCP";
    auth_basic_user_file /etc/nginx/remarkable-mcp.htpasswd;

    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_read_timeout 3600s;

    # Required by MCPServer's default DNS-rebinding protection.
    proxy_set_header Host 127.0.0.1:8000;
    proxy_set_header Origin "";
}

No expongas el puerto upstream directamente. Configura OpenWebUI con la URL del proxy autenticado, como https://mcp.example.com/mcp.

Para NixOS, remarkable-mcp-bridge.nix proporciona un módulo systemd con el mismo valor predeterminado de bucle local:

{
  imports = [ ./remarkable-mcp-bridge.nix ];
  services.remarkable-mcp = {
    enable = true;
    command = "/opt/remarkable-mcp/.venv/bin/remarkable-mcp";
  };
}

El usuario del servicio debe tener sus credenciales de reMarkable en /var/lib/remarkable-mcp (o en el home configurado). El módulo añade Tesseract a la ruta de búsqueda de ejecutables del servicio; instala el command configurado por separado.

Integración con OpenClaw

remarkable-mcp funciona como una habilidad de OpenClaw. Añádelo a tu openclaw.json:

{
  "mcpServers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--usb"]
    }
  }
}

Instálalo desde ClawHub:

clawhub install remarkable-mcp

O copia el SKILL.md de este repositorio a tu directorio ~/.openclaw/skills/remarkable-mcp/.

Herramientas

Las herramientas de lectura/búsqueda/renderizado son de solo lectura. remarkable_export nunca cambia la tableta, pero escribe un archivo temporal acotado en el host del servidor MCP y por tanto declara readOnlyHint=false. Los enlaces de exportación caducan a los 15 minutos y el servidor conserva como máximo ocho a la vez. Los transportes compatibles también registran herramientas de escritura de forma predeterminada; pasa --read-only para desactivarlas. Consulta Herramientas de escritura. Los clientes que admiten Aplicaciones MCP también pueden abrir remarkable_canvas.

Referencia completa de herramientas

Comportamiento de las herramientas

• Navegar por una ruta de documento devuelve su contenido.

• El texto vacío de un cuaderno puede activar OCR automáticamente.

• La búsqueda puede examinar varios documentos coincidentes.

• Las herramientas de imagen devuelven contenido visual que la extracción de texto no capta.

• remarkable_read.total_pages es el recuento físico de documentos; content_pages cuenta los fragmentos de texto extraídos, y more / next_page continúan esos fragmentos. Las lecturas de PDF sin procesar cuentan las páginas del PDF ya descargado. Si un archivo EPUB sin procesar no puede leerse, su texto se devuelve igualmente con total_pages: null y total_pages_known: false.

• Las imágenes PNG de páginas con respaldo PDF fusionan la página de origen y las anotaciones automáticamente; pasa render_merged=False para obtener solo la capa de anotaciones.

• Las exportaciones PDF conservan el orden físico de las páginas y fusionan las capas subyacentes mapeadas con las anotaciones de forma predeterminada. Las exportaciones Markdown mantienen las secciones fijas de origen/escritura/anotación/OCR sin adivinar la estructura del documento.

• El OCR usa Google Vision cuando está configurado y, de lo contrario, se ejecuta localmente con Tesseract.

• Navegar y buscar aceptan filtros de etiquetas.

Ejemplo de uso

# Read a document
remarkable_read("Meeting Notes")

# Search for keywords
remarkable_read("Project Plan", grep="deadline")

# Enable OCR for handwritten notes
remarkable_read("Journal", include_ocr=True)

# Browse your library
remarkable_browse("/Work/Projects")

# Filter by tags
remarkable_browse("/", tags=["important"])
remarkable_browse("/Work", tags=["project", "active"])

# Search across documents
remarkable_search("meeting", grep="action items")

# Search with tag filter
remarkable_search("project", tags=["work"])

# Get recent documents
remarkable_recent(limit=10)

# Get a page image (for visual content like UI mockups or diagrams)
remarkable_image("UI Mockup", page=1)

# Get SVG for editing in design tools
remarkable_image("Wireframe", output_format="svg")

# Get image with OCR text extraction
remarkable_image("Handwritten Notes", include_ocr=True)

# Imported PDF pages include their reMarkable annotations automatically
remarkable_image("Research Paper", page=3)

# Request only the reMarkable annotation layer
remarkable_image("Research Paper", page=3, render_merged=False)

# Transparent background for compositing
remarkable_image("Logo Sketch", background="#00000000")

# Compatibility mode: return resource URI instead of embedded resource
remarkable_image("Diagram", compatibility=True)

# Export a complete PDF through a temporary MCP ResourceLink
remarkable_export("Meeting Notes")

# Export honest, sectioned Markdown with opt-in OCR
remarkable_export("Journal", output_format="markdown", include_ocr=True)

# Export only full-page annotation layers when archive data is available
remarkable_export("Research Paper", pdf_mode="annotations")

Nota: El renderizado PNG usa PyMuPDF tanto para los SVG de cuadernos como para los PDF, por lo que remarkable_image no requiere Cairo, Inkscape, Chromium ni ningún otro runtime gráfico del sistema. Si el análisis de trazos local no puede procesar una página, los modos USB y SSH recurren a la exportación PDF nativa de la tableta y el modo nube recurre al PDF de origen original cuando existe.

Recursos

Los documentos se registran automáticamente como recursos MCP:

Los documentos en la papelera se excluyen de la búsqueda por herramienta, lienzo y recurso, de modo que un elemento en la papelera no puede hacer sombra a un documento activo con el mismo nombre.

remarkable_export devuelve un ResourceLink en lugar de incrustar contenido de archivo potencialmente grande en la respuesta de la herramienta. El servidor almacena el archivo en un directorio temporal privado durante 15 minutos, conserva como máximo ocho exportaciones y elimina las exportaciones gestionadas al apagarse. Obtén y guarda el recurso enlazado para un uso duradero.

Referencia completa de recursos

OCR

Para contenido manuscrito, remarkable-mcp ofrece dos motores de OCR:

Configuración rápida

Establece REMARKABLE_OCR_BACKEND en tu configuración de MCP:

{
  "env": {
    "REMARKABLE_OCR_BACKEND": "auto"
  }
}

Opciones: auto, google, tesseract

1. Habilita la API de Cloud Vision

2. Crea una clave de API

3. Añádela a la configuración: "GOOGLE_VISION_API_KEY": "tu-clave"

Coste: 1.000 solicitudes gratuitas al mes, luego ~1,50 $ por cada 1.000.

Guía de configuración de Google Vision

OCR de código abierto diseñado para texto impreso. Resultados deficientes con escritura a mano, pero útil como alternativa sin conexión.

# Install Tesseract
# macOS
brew install tesseract

# Ubuntu/Debian
sudo apt install tesseract-ocr

# Windows
choco install tesseract

Comportamiento predeterminado (auto)

Cuando REMARKABLE_OCR_BACKEND=auto (predeterminado):

1. Google Vision (si GOOGLE_VISION_API_KEY está definida)

2. Tesseract (alternativa)

Herramientas de escritura por transporte

Las herramientas de escritura permiten subir, organizar y gestionar documentos en tu reMarkable. Habilitadas de forma predeterminada en los transportes con capacidad de escritura. Los modos nube y SSH admiten el conjunto completo; el modo USB web solo admite la subida (su firmware no expone operaciones de carpetas); el modo de directorio local es siempre de solo lectura. Pasa --read-only para exponer un servidor de solo lectura en otro lugar.

Desactivación de las herramientas de escritura (modo de solo lectura)

Las herramientas de escritura están activadas de forma predeterminada en cada modo con capacidad de escritura. El modo de directorio local es siempre de solo lectura. Para hacer que otro transporte sea de solo lectura, añade la marca --read-only:

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--read-only"]
    }
  }
}

Se combina con cualquier marca de transporte (--ssh, --usb):

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--ssh", "--read-only"]
    }
  }
}

O establece la variable de entorno:

{
  "env": {
    "REMARKABLE_READ_ONLY": "1"
  }
}

La marca heredada --write y la variable REMARKABLE_ENABLE_WRITE todavía se aceptan por compatibilidad hacia atrás, pero ahora son operaciones nulas (la escritura es el valor predeterminado). --write y --read-only son mutuamente excluyentes.

Herramientas de escritura disponibles

Seguridad

• Subida de registros en modo nube, SSH y USB web — el modo de directorio local nunca expone herramientas de escritura.

• mkdir, move, rename, delete se registran solo en modos nube y SSH — no se exponen en USB web (el firmware USB web de la tableta no tiene endpoints de carpeta/mover/renombrar/eliminar), manteniendo la lista de herramientas limitada a lo que el transporte activo realmente soporta.

• Delete solicita confirmación cuando es posible — si el cliente admite la elicitación MCP, remarkable_delete pide al usuario que confirme antes de eliminar. El MCP SDK 2.x transporta esa solicitud como una petición de entrada de varias rondas para clientes 2026-07-28 y como elicitación push para clientes heredados. Si el cliente no puede mostrar una solicitud, el borrado se rechaza (no se realiza) a menos que REMARKABLE_SKIP_CONFIRM=1 esté definido — de modo que la escritura activada por defecto no puede eliminar silenciosamente desde clientes que carecen de elicitación. La nube y SSH mueven los elementos a la Papelera por defecto. SSH también admite permanent=True para una eliminación permanente solicitada explícitamente; la eliminación permanente en la nube sigue siendo una operación de gestión de la Papelera en la app/tableta. Define REMARKABLE_SKIP_CONFIRM=1 para permitir borrados sin solicitud en entornos automatizados. Todas las herramientas de escritura llevan ToolAnnotations(read_only_hint=False) (y destructive_hint=True para delete) para que un harness de agente pueda controlar las escrituras en la capa MCP.

• El trabajo SSH es justo y serializado por servidor — un despachador FIFO es dueño de cada subproceso SSH, de modo que los escaneos de inicio, lecturas, subidas, mutaciones y sondeos de refresco no pueden saturar la conexión USB CDC de la tableta de forma concurrente. Las lecturas de metadatos en caché omiten la cola.

• Las escrituras SSH concurrentes comparten una barrera de refresco — las escrituras casi simultáneas se persisten en orden FIFO, y luego cada llamada participante espera un reinicio compartido de xochitl antes de informar éxito. Un debounce acotado fusiona ráfagas sin éxito en segundo plano ni tardío.

• Los refrescos SSH evitan la ruta de reinicio de emergencia del firmware — el refresco serializado limpia solo el contador de inicio de systemd de xochitl inmediatamente antes del reinicio, y luego requiere sesiones SSH estables y no multiplexadas en el mismo arranque. Los alias de OpenSSH se resuelven con ssh -G; si USB web era accesible en ese host efectivo antes del reinicio, el puerto 80 también debe recuperarse. Un sondeo fallido mantiene refresh_pending: true y nunca reproduce la escritura.

• Los reintentos son deliberadamente limitados — solo los fallos de conexión que demuestran que el comando remoto nunca se inició (por ejemplo, conexión rechazada, tiempo de conexión agotado o tiempo de banner agotado) reciben retroceso exponencial acotado. Los fallos de escritura ambiguos o posteriores al inicio nunca se reproducen; el error dirige al llamante a refrescar e inspeccionar la tableta en su lugar.

• Para operaciones masivas explícitas, pasa defer_restart=True a cada escritura (incluida remarkable_author) — o define REMARKABLE_DEFER_RESTART=1 — y llama a remarkable_refresh() una vez al final. Las escrituras diferidas regresan inmediatamente con refresh_pending: true; un refresco adicional es un no-op solo después de que el proceso del servidor actual haya confirmado un estado limpio. Un proceso nuevo realiza un refresco de recuperación conservador porque no puede saber si un proceso anterior dejó cambios de disco pendientes.

• Una escritura SSH de varios pasos que falla después de cualquier mutación confirmada devuelve write_partially_persisted, indica no repetir e informa si la recuperación de refresco sigue pendiente. Un fallo de refresco compartido se propaga solo a los participantes cuya propia mutación estaba sucia; los fallos limpios de validación/pre-ejecución conservan su error original.

• Las solicitudes HTTP USB usan el mismo núcleo de operación acotado con REMARKABLE_USB_MAX_CONCURRENCY (por defecto 2). La sincronización en la nube mantiene su capa de solicitudes existente, agrupada y consciente de idempotencia, y el control REMARKABLE_SYNC_WORKERS.

Ejemplos

# Upload a PDF
remarkable_upload("paper.pdf", parent_folder="/Research")

# Render Markdown and upload the PDF without creating a local file
remarkable_markdown_to_pdf(
    "# Meeting Notes\n\n- Follow up with Sam",
    document_name="Meeting Notes",
    parent_folder="/Research",
)

# Create a folder
remarkable_mkdir("2024 Archive", parent="/Archive")

# Move a document
remarkable_move("Meeting Notes", "/Archive/2024 Archive")

# Rename a document
remarkable_rename("Untitled", "Q4 Planning Notes")

# Delete (destructive; confirms via elicitation when supported)
remarkable_delete("Old Draft")

# Permanently delete in SSH mode only
remarkable_delete("Disposable Test", permanent=True)

# Bulk import (SSH): defer the restart on each write, then refresh once.
# One xochitl restart for the whole batch instead of one per upload.
remarkable_upload("a.pdf", parent_folder="/Research", defer_restart=True)
remarkable_upload("b.pdf", parent_folder="/Research", defer_restart=True)
remarkable_refresh()

# Author native ink and notebooks (SSH only)
# Append pen/highlighter strokes to a page (coordinates normalized [0,1] from
# the page's top-left). The interactive canvas Save button calls this too.
remarkable_author(
    method="draw", document="Ideas", page=1,
    strokes=[{"points": [[0.1, 0.2], [0.8, 0.2]], "tool": "highlighter", "color": "yellow"}],
)

# Append a blank, drawable page to the end of a notebook
remarkable_author(method="add_page", document="Ideas")

# Create a new blank notebook
remarkable_author(method="create_document", name="Sketches")

# Only seed typed text when the user explicitly requested it.
remarkable_author(method="create_document", name="Meeting notes", text="Agenda\nFollow-ups")

Aplicación de lienzo interactivo (MCP Apps)

Un visor de páginas interactivo construido sobre la extensión MCP Apps (SEP-1865). Los clientes que admiten MCP Apps (como ChatGPT, Claude, VS Code y MCP Inspector) renderizan un lienzo en un panel lateral donde puedes ver una página de documento y navegar por ella.

No hay ninguna bandera para activarlo — la herramienta remarkable_canvas y su recurso ui://remarkable/canvas están siempre registrados, y la capacidad se negocia automáticamente en las capacidades del cliente (descubrimiento moderno o un handshake initialize heredado). Los clientes con capacidad de app abren el lienzo interactivo; cualquier otro cliente simplemente recibe la página renderizada como imagen, por lo que la herramienta es segura y útil en todas partes.

Esto registra una herramienta:

Cómo se comporta:

• Clientes con capacidad de app abren el lienzo (declarado en ui://remarkable/canvas, MIME text/html;profile=mcp-app) y pueden pasar páginas del documento a través del puente postMessage de MCP Apps — el servidor entrega cada página renderizada en el structuredContent del resultado del wire (structured_content en Python).

• Otros clientes siguen recibiendo la página renderizada como una imagen PNG incrustada, por lo que la herramienta es útil en todas partes; simplemente no abrirá el panel interactivo. Los metadatos _meta.ui / ui:// son inertes para los clientes que no anuncian la extensión de UI de MCP Apps.

Dibujo y creación desde el lienzo

Cuando el modo de escritura está activado (el predeterminado) y el transporte activo es SSH, el lienzo se convierte en una superficie de escritura:

• Dibujar: elige un lápiz o rotulador, dibuja y luego guarda la tinta nativa .rm en el dispositivo.

• Añadir página: pon en cola una página de cuaderno nativa en blanco, dibuja en ella y luego guarda.

• Una única fuente de verdad: el lienzo llama a la misma herramienta remarkable_author que llamaría un modelo (method="draw" al guardar, method="add_page" para ＋Page), de modo que la ruta humana y la ruta del modelo producen resultados byte-idénticos.

Los controles Guardar / Dibujar / ＋Page están ocultos cuando la página no es escribible (modo de solo lectura o un transporte que no sea SSH), y el lienzo vuelve a un visor de imágenes simple. El puente iframe sigue la especificación de MCP Apps, pero es mejor validarlo contra tu cliente específico.

Configuración avanzada

Filtrado de ruta raíz

Limita el servidor MCP a una carpeta específica en tu reMarkable. Todas las operaciones se limitarán a esta carpeta:

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--ssh"],
      "env": {
        "REMARKABLE_ROOT_PATH": "/Work",
        "GOOGLE_VISION_API_KEY": "your-api-key"
      }
    }
  }
}

Con esta configuración:

• remarkable_browse("/") muestra el contenido de /Work

• remarkable_browse("/Projects") muestra /Work/Projects

• Los documentos fuera de /Work no son accesibles

Útil para:

• Centrarse en documentos de trabajo durante el horario de oficina

• Separar notas personales y profesionales

• Limitar el alcance para flujos de trabajo de IA específicos

Color de fondo personalizado

Define el color de fondo predeterminado para el renderizado de imágenes:

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--ssh"],
      "env": {
        "REMARKABLE_BACKGROUND_COLOR": "#FFFFFF"
      }
    }
  }
}

Formatos admitidos:

• #RRGGBB: hex RGB, como #FFFFFF

• #RRGGBBAA: hex RGBA, como #00000000

El valor predeterminado es #FBFBFB (color de papel reMarkable). Esto afecta tanto a la herramienta remarkable_image como a los recursos de imagen.

Configuración de reintentos

Las solicitudes a la API en la nube se reintentan automáticamente ante fallos transitorios (HTTP 429, 500, 502, 503, 504) y errores de red con retroceso exponencial y jitter. Puedes ajustar esto mediante variables de entorno:

Los reintentos por límite de tasa respetan los valores Retry-After numéricos y en fecha HTTP, con un tope de 20 segundos. Los fallos de autenticación activan la renovación del token en lugar de reintentar.

Rendimiento y caché en la nube

El modo nube está diseñado para hacer rápido un flujo de trabajo sin dispositivo:

• Recorrido en paralelo: obtener metadatos de documentos de forma concurrente.

• Agrupación de conexiones: reutilizar conexiones HTTP.

• Caché de blobs direccionada por contenido: reutilizar blobs inmutables por hash y obtener nuevos hashes cuando los documentos cambian.

Normalmente no necesitas configurar nada de esto, pero estas variables de entorno te permiten ajustarlo:

La caché es puramente un acelerador local: eliminar REMARKABLE_CACHE_DIR solo obliga a la siguiente lectura a volver a descargar. El hash raíz mutable de la nube siempre se obtiene fresco, por lo que nunca ves una biblioteca obsoleta.

Flujos de trabajo comunes

• Leer notas recientes y extraer elementos de acción.

• Buscar nombres, etiquetas, texto escrito y salida de OCR.

• Revisar PDFs anotados con la página de origen y las anotaciones juntas.

• Mover notas seleccionadas a otro flujo de trabajo local.

• Subir PDFs de referencia o documentos Markdown generados.

Documentación

Desarrollo

git clone https://github.com/SamMorrowDrums/remarkable-mcp.git
cd remarkable-mcp
uv sync --all-extras
uv run pytest -v

Guía de desarrollo

Prueba de humo multi-transporte

Cuando algo parece roto, ejecuta primero la prueba de humo determinista y sin IA. Esta prueba maneja el servidor real a través de MCP y ejercita todas las herramientas disponibles en cada transporte alcanzable en este orden: directorio local, nube, USB web y luego SSH.

uv run python smoke/run_smoke.py            # all available modes
uv run python smoke/run_smoke.py --read-only # connectivity + reads only

Guía de prueba de humo y expectativas por modo.

Licencia

MIT

Construido con rmscene, PyMuPDF, markdown-it-py e inspiración de ddvk/rmapi.