# reMarkable MCP Server [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/SamMorrowDrums/remarkable-mcp  
**GitHub Stars:** 266  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/remarkable-mcp-server

## Description
Access your reMarkable tablet - read documents, browse files, extract text and OCR

## Tools
Capabilities this server exposes over MCP:

- **remarkable_read** — 
    <usecase>Read and extract text content from a reMarkable document.</usecase>
    <instructions>
    Extracts content from a document with pagination to preserve context window.

    Content types:
    - "text" (default): Full extracted text (PDF/EPUB content + annotations)
    - "raw": Original PDF/EPUB text only (no annotations). Works in every
      transport, as long as the source file is present (very large PDFs/EPUBs
      may not be synced to the cloud).
    - "annotations": Only annotations, highlights, and handwritten notes

    Use pagination to read large documents without overwhelming context:
    - Start with page=1 (default)
    - Check "more" field - if true, there's more content
    - Use "next_page" value to get the next page
    - "total_pages" is the physical document count; "content_pages" is the
      extracted-text count used by page/more/next_page
    - "total_pages_known" reports whether the physical count was available.
      Raw PDF reads count the downloaded PDF directly. If a raw EPUB archive
      cannot be read, content still returns with total_pages=null.
    - If older USB firmware returns only a native PDF, "text" returns source
      text without annotations and "annotations" reports that the archive is
      unavailable instead of trying to parse the PDF as a zip.

    Use grep to search for specific content on the current page.

    OCR uses Google Vision when configured, otherwise Tesseract.
    </instructions>
    <parameters>
    - document: Document name or path (use remarkable_browse to find documents)
    - content_type: "text" (full), "raw" (PDF/EPUB only), "annotations" (notes only)
    - page: Extracted-content page number (default: 1). Physical document pages
      are reported separately as total_pages.
    - grep: Optional regex pattern to filter content (searches current page)
    - include_ocr: Enable handwriting OCR for annotations (default: False)
    </parameters>
    <examples>
    - remarkable_read("Meeting Notes")  # Get first page of text
    - remarkable_read("Book.pdf", content_type="raw")  # Get raw PDF text
    - remarkable_read("Notes", content_type="annotations")  # Only annotations
    - remarkable_read("Report", page=2)  # Get second page
    - remarkable_read("Manual", grep="installation")  # Search for keyword
    </examples>
    
- **remarkable_browse** — 
    <usecase>Browse your reMarkable library or search for documents.</usecase>
    <instructions>
    Three modes:
    1. Browse mode (default): List contents of a folder
       - Use path="/" for root folder
       - Use path="/FolderName" to navigate into folders
    2. Search mode: Find documents by name
       - Set query="search term" to search across all documents
    3. Filter by tags: Find documents with specific tags
       - Set tags=["tag1", "tag2"] to filter by tags
       - Works in both browse and search modes

    Results include document names, types, modification dates, and tags.

    Note: If REMARKABLE_ROOT_PATH is configured, only documents within that
    folder are accessible. Paths are relative to the root path.
    </instructions>
    <parameters>
    - path: Folder path to browse (default: "/" for root)
    - query: Search term to find documents by name (optional, triggers search mode)
    - tags: List of tags to filter documents (optional, case-insensitive)
    </parameters>
    <examples>
    - remarkable_browse()  # List root folder
    - remarkable_browse("/Work")  # List Work folder
    - remarkable_browse(query="meeting")  # Search for "meeting"
    - remarkable_browse(tags=["important"])  # Show documents with "important" tag
    - remarkable_browse(query="project", tags=["work"])  # Search with tag filter
    </examples>
    
- **remarkable_recent** — 
    <usecase>Get your most recently modified documents.</usecase>
    <instructions>
    Returns documents sorted by modification date (newest first).
    Optionally includes a text preview of each document's content.

    Use this to quickly find what you were working on recently.

    Note: If REMARKABLE_ROOT_PATH is configured, only documents within that
    folder are included.
    </instructions>
    <parameters>
    - limit: Maximum documents to return (default: 10, max: 50 without preview, 10 with preview)
    - include_preview: Include first ~200 chars of text content (default: False)
    </parameters>
    <examples>
    - remarkable_recent()  # Last 10 documents
    - remarkable_recent(limit=5, include_preview=True)  # With content preview
    </examples>
    
- **remarkable_search** — 
    <usecase>Search across multiple documents and return matching content.</usecase>
    <instructions>
    Searches document names for the query, then optionally searches content with grep.
    Can filter by tags to narrow results.
    Returns summaries from multiple documents in a single call.

    This is efficient for finding information across your library without
    making many individual tool calls.

    Limits:
    - Max 5 documents per search (to keep response size manageable)
    - Returns first page (~8000 chars) of each matching document
    - Use grep to filter to relevant sections
    </instructions>
    <parameters>
    - query: Search term for document names
    - grep: Optional pattern to search within document content
    - limit: Max documents to return (default: 5, max: 5)
    - include_ocr: Enable OCR for handwritten content (default: False)
    - tags: List of tags to filter documents (optional, case-insensitive)
    </parameters>
    <examples>
    - remarkable_search("meeting")  # Find docs with "meeting" in name
    - remarkable_search("journal", grep="project")  # Find "project" in journals
    - remarkable_search("notes", include_ocr=True)  # Search with OCR enabled
    - remarkable_search("project", tags=["work"])  # Find work-tagged projects
    </examples>
    
- **remarkable_status** — 
    <usecase>Check connection status, active transport, and write capabilities.</usecase>
    <instructions>
    Returns authentication status, the active transport (cloud, local-dir, ssh, or
    usb-web), the document count, and a capability matrix describing what each
    transport can do. Use this to verify your connection, choose a transport, or
    troubleshoot.

    Capability notes:
    - Export is available in every transport and creates only a bounded temporary
      local resource; it never modifies the tablet.
    - Cloud (default): full read/render/export/upload/mkdir/move/rename/delete — no device
      needed, works from anywhere your token is valid.
    - SSH: full capabilities over a local/USB connection to the tablet.
    - USB web: read, render, export, and upload (to root) only — the tablet's USB web
      interface firmware exposes no folder/move/rename/delete endpoints. For full
      write parity over a USB cable, use SSH mode pointed at the USB IP.
    - Local directory: fully offline read/render/export access to the desktop app's sync
      cache. Strictly read-only to avoid corrupting app-managed state.
    Write tools (upload/mkdir/move/rename/delete) are enabled by default; run
    with --read-only (or REMARKABLE_READ_ONLY=1) to expose a read-only server.
    </instructions>
    <examples>
    - remarkable_status()
    </examples>
    
- **remarkable_image** — 
    <usecase>Get an image of a specific page from a reMarkable document.</usecase>
    <instructions>
    Renders a notebook or document page as an image (PNG or SVG). This is useful for:
    - Viewing hand-drawn diagrams, sketches, or UI mockups
    - Getting visual context that text extraction might miss
    - Implementing designs based on hand-drawn wireframes
    - SVG format for scalable vector graphics that can be edited

    ## Merged PDF + Annotation Rendering

    PNG pages backed by an imported PDF automatically composite the PDF page with
    its reMarkable annotations. Set render_merged=False for an annotation-only
    render, or True to explicitly request compositing. SVG remains annotation-only.

    ## Response Formats

    By default, images are returned as embedded resources (EmbeddedResource) which
    include the full image data inline:
    - PNG: Returned as BlobResourceContents with base64-encoded data
    - SVG: Returned as TextResourceContents with SVG markup

    If your client doesn't support embedded resources in tool responses, set
    compatibility=True to receive a JSON response with just the resource URI.
    The client can then fetch the resource separately.

    Optionally, enable include_ocr=True to extract text from the image using OCR.
    Google Vision is used when configured; otherwise OCR runs locally with Tesseract.

    Note: Native notebooks retain their existing stroke rendering behavior.
    If older USB firmware returns only a native PDF export, PNG remains
    available; SVG and explicit annotation-only rendering require an rmdoc
    archive and return a clear error when it is unavailable.
    </instructions>
    <parameters>
    - document: Document name or path (use remarkable_browse to find documents)
    - page: Page number (default: 1, 1-indexed)
    - background: Background color as hex code. Supports RGB (#RRGGBB) or RGBA (#RRGGBBAA).
      Default is "#FBFBFB" (reMarkable paper color), or set REMARKABLE_BACKGROUND_COLOR
      env var to override. Use "#00000000" for transparent.
    - output_format: Output format - "png" (default) or "svg" for vector graphics
    - compatibility: If True, return resource URI in JSON instead of embedded resource.
      Use this if your client doesn't support embedded resources in tool responses.
    - include_ocr: Enable OCR text extraction from the image (default: False).
    - render_merged: PDF compositing mode for PNG: None (default) automatically
      merges PDF-backed pages, True explicitly requests merging, and False returns
      the annotation-only layer. SVG output remains annotation-only.
    </parameters>
    <examples>
    - remarkable_image("UI Mockup")  # Get first page as embedded PNG resource
    - remarkable_image("Meeting Notes", page=2)  # Get second page
    - remarkable_image("/Work/Designs/Wireframe", background="#FFFFFF")  # White background
    - remarkable_image("Sketch", background="#00000000")  # Transparent background
    - remarkable_image("Diagram", output_format="svg")  # Get as embedded SVG resource
    - remarkable_image("Notes", compatibility=True)  # Return resource URI for retry
    - remarkable_image("Notes", include_ocr=True)  # Get image with OCR text extraction
    - remarkable_image("Annotated PDF")  # PDF + annotations composited automatically
    - remarkable_image("Annotated PDF", render_merged=False)  # Annotation layer only
    </examples>
    
- **remarkable_export** — 
    <usecase>Export one reMarkable document as a reusable PDF or Markdown file.</usecase>
    <instructions>
    Exports a single document without modifying the tablet or its library.

    The generated file is written to a server-managed temporary directory and
    returned as an MCP ResourceLink. The tool response stays small: it never embeds
    the PDF/Markdown as base64 and never writes to an arbitrary host path. The
    resource expires after 15 minutes and may be evicted earlier when more than
    eight exports are retained. Fetch and save the linked resource for durable use.

    PDF behavior:
    - `pdf_mode="merged"` (default) preserves complete physical pages, combining
      mapped PDF underlays and reMarkable annotations.
    - `pdf_mode="annotations"` exports full-page annotation layers only when the
      transport provides a document archive.
    - Pages remain in physical device order. A render failure produces a labeled
      placeholder at that ordinal and a partial-export warning; pages are not skipped.

    Markdown behavior:
    - Preserves basic source metadata and fixed source text, typed text, annotation,
      highlight, and OCR sections.
    - OCR is opt-in and uses the same configured/cached OCR path as remarkable_read.
    - Extracted text is kept verbatim; the exporter does not invent headings, lists,
      links, or page attribution it cannot prove.
    </instructions>
    <parameters>
    - document: Document name or path (use remarkable_browse to find documents).
    - output_format: "pdf" (default) or "markdown".
    - pdf_mode: PDF-only mode, "merged" (default) or "annotations".
    - include_ocr: Enable existing handwriting OCR for Markdown (default: False).
    </parameters>
    <examples>
    - remarkable_export("Meeting Notes")
    - remarkable_export("Research Paper", output_format="pdf", pdf_mode="annotations")
    - remarkable_export("Journal", output_format="markdown", include_ocr=True)
    </examples>
    
- **remarkable_upload** — 
        <usecase>Upload a PDF or EPUB file to the reMarkable tablet.</usecase>
        <instructions>
        Uploads a local file to the tablet. Only PDF and EPUB formats
        are supported. Works in all three transports:
        - Cloud: uploaded via the sync protocol; supports parent_folder + document_name
        - SSH: transferred over SSH, metadata created; supports parent_folder + document_name
        - USB web: uploaded via POST /upload. The multipart filename carries
          document_name, parent_folder is ignored, and the tablet web service
          chooses the destination folder.

        Requires write mode (the default; disabled with --read-only).
        </instructions>
        <parameters>
        - file_path: Absolute path to the local PDF or EPUB file
        - parent_folder: Destination folder path on tablet (default: root "/").
          Honored in cloud and SSH modes; ignored by the USB web interface.
        - document_name: Display name on tablet (default: filename without
          extension). Honored in every mode; USB web uses it as the uploaded filename.
        - defer_restart: SSH only. When True, skip the xochitl restart that
          normally makes the upload visible. Use this for every upload in a
          batch, then call remarkable_refresh() ONCE at the end. Each restart
          forces a full document-store rescan that briefly destabilises the SSH
          link, so deferring turns N restarts (and N races) into one. The
          response sets "refresh_pending": true while a refresh is owed. Ignored
          in cloud/USB modes (no xochitl).
        </parameters>
        <examples>
        - remarkable_upload("/tmp/paper.pdf")
        - remarkable_upload("/tmp/book.epub", parent_folder="/Books")
        - remarkable_upload("/tmp/report.pdf", document_name="Q4 Report")
        - # batch import: defer every upload, refresh once at the end
          remarkable_upload("/tmp/a.pdf", defer_restart=True)
          remarkable_upload("/tmp/b.pdf", defer_restart=True)
          remarkable_refresh()
        </examples>
        
- **remarkable_markdown_to_pdf** — 
        <usecase>Render Markdown text as a PDF and upload it to the reMarkable tablet.</usecase>
        <instructions>
        Use this when the user wants notes, reports, summaries, or other Markdown
        content written back to the tablet without first creating a local file.
        Headings, lists, tables, links, blockquotes, and code blocks are rendered
        into a paginated A4 PDF. Raw HTML is escaped and image assets are omitted
        so rendering never reads local files or fetches remote content.

        Works in all three transports:
        - Cloud: sync upload with parent_folder and document_name
        - SSH: filesystem upload with parent_folder and document_name
        - USB web: upload whose multipart filename is document_name + ".pdf";
          parent_folder is ignored and the tablet web service chooses the folder.

        Requires write mode (the default; disabled with --read-only).
        </instructions>
        <parameters>
        - markdown: Markdown source text. Must not be empty.
        - document_name: Display name on the tablet (default: "Markdown").
        - parent_folder: Destination folder (default: root "/"). USB web ignores
          this parameter because its upload endpoint has no folder argument.
        - defer_restart: SSH only. When True, skip the xochitl restart and call
          remarkable_refresh() once after the batch. Forwarded exactly like
          remarkable_upload; ignored in cloud and USB web modes.
        </parameters>
        <examples>
        - remarkable_markdown_to_pdf("# Meeting Notes\n\n- Follow up with Sam")
        - remarkable_markdown_to_pdf(
            "# Q4 Report\n\nRevenue increased **20%**.",
            document_name="Q4 Report",
            parent_folder="/Reports",
          )
        - remarkable_markdown_to_pdf(
            "# Batch item", document_name="Item 1", defer_restart=True
          )
          remarkable_refresh()
        </examples>
        
- **remarkable_mkdir** — 
            <usecase>Create a new folder on the reMarkable tablet.</usecase>
            <instructions>
            Creates a folder in the tablet's document hierarchy. In SSH mode the
            folder appears after xochitl restarts; in cloud mode it syncs to all
            your devices.

            Works in cloud and SSH modes (default; --read-only disables). Not available over the
            USB web interface (the firmware exposes no folder-create endpoint).
            </instructions>
            <parameters>
            - folder_name: Name of the new folder
            - parent: Parent folder path (default: root "/")
            - defer_restart: SSH only. Skip the xochitl restart so a batch of
              writes can refresh once via remarkable_refresh() instead of once
              per write. Sets "refresh_pending": true. Ignored in cloud mode.
            </parameters>
            <examples>
            - remarkable_mkdir("Projects")
            - remarkable_mkdir("2024", parent="/Archive")
            </examples>
            
- **remarkable_move** — 
            <usecase>Move a document or folder to a different location.</usecase>
            <instructions>
            Moves a document or folder by updating its parent reference in the metadata.
            Find the document name with remarkable_browse() first.

            Works in cloud and SSH modes (default; --read-only disables). Not available over the
            USB web interface.
            </instructions>
            <parameters>
            - document: Name or path of the document/folder to move
            - dest_folder: Destination folder path (use "/" for root)
            - defer_restart: SSH only. Skip the xochitl restart so a batch of
              writes can refresh once via remarkable_refresh() instead of once
              per write. Sets "refresh_pending": true. Ignored in cloud mode.
            </parameters>
            <examples>
            - remarkable_move("Meeting Notes", "/Archive")
            - remarkable_move("Old Project", "/Archive/2023")
            </examples>
            
- **remarkable_rename** — 
            <usecase>Rename a document or folder on the reMarkable tablet.</usecase>
            <instructions>
            Changes the display name of a document or folder by updating its metadata.
            Find the document name with remarkable_browse() first.

            Works in cloud and SSH modes (default; --read-only disables). Not available over the
            USB web interface.
            </instructions>
            <parameters>
            - document: Current name or path of the document/folder
            - new_name: New display name
            - defer_restart: SSH only. Skip the xochitl restart so a batch of
              writes can refresh once via remarkable_refresh() instead of once
              per write. Sets "refresh_pending": true. Ignored in cloud mode.
            </parameters>
            <examples>
            - remarkable_rename("Untitled", "Meeting Notes 2024-01-15")
            - remarkable_rename("/Work/Draft", "Final Report")
            </examples>
            
- **remarkable_delete** — 
            <usecase>Delete a document or folder on the reMarkable tablet.</usecase>
            <instructions>
            DESTRUCTIVE operation. By default the item is moved to the tablet's
            Trash and remains recoverable. In SSH mode only, permanent=True removes
            the resolved UUID and all sidecar files instead; use that only when the
            user explicitly asked for permanent deletion.

            Works in cloud and SSH modes (default; --read-only disables). Not available over the
            USB web interface.

            If the client supports elicitation, this tool asks the user to confirm
            before deleting. If the client cannot show a confirmation prompt, the
            delete is refused unless REMARKABLE_SKIP_CONFIRM=1 is set (for headless
            automation).
            </instructions>
            <parameters>
            - document: Name or path of the document/folder to delete
            - defer_restart: SSH only. Skip the xochitl restart so a batch of
              deletes can refresh once via remarkable_refresh() instead of once
              per delete. Sets "refresh_pending": true. Ignored in cloud mode.
            - permanent: SSH only. Permanently remove the resolved document/folder
              files instead of moving the item to Trash (default: False).
            </parameters>
            <examples>
            - remarkable_delete("Old Notes")
            - remarkable_delete("/Books/Archive/Old Draft")
            </examples>
            
- **remarkable_canvas** — 
        <usecase>Open a reMarkable page in an interactive canvas viewer.</usecase>
        <instructions>
        Renders a notebook or document page and, in clients that support MCP Apps
        interactive UI, opens a canvas viewer that lets the user page through the
        document. This is the entry point for the interactive viewer.

        The canvas is currently a read-only viewer (render + page navigation).
        For plain image extraction without the interactive surface, use
        remarkable_image instead.

        Clients that do not support MCP Apps still get the rendered page back as
        an embedded PNG image, so this tool is useful everywhere; it just won't
        open the interactive panel.
        </instructions>
        <parameters>
        - document: Document name or path (use remarkable_browse to find documents)
        - page: Page number to open (default: 1, 1-indexed)
        </parameters>
        <examples>
        - remarkable_canvas("Meeting Notes")
        - remarkable_canvas("/Work/Sketches/Wireframe", page=3)
        </examples>
        

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## What reMarkable MCP Server does

reMarkable MCP Server exposes a reMarkable library through MCP tools. It can list folders, search document names and tags, identify recently modified files, extract source text and annotations, render pages as PNG or SVG, and export documents as PDF or Markdown. Handwriting OCR is available through Google Vision when configured, with Tesseract as the local fallback.

The server also supports selected write operations. It can upload PDF and EPUB files, convert Markdown into a paginated A4 PDF and upload it, create folders, move or rename items, and delete documents or folders. Deletion normally moves an item to Trash; permanent removal is available only through SSH and is intended for explicit permanent-delete requests.

## How it works

The server can run over stdio or local Streamable HTTP. Its connection modes determine where document data comes from and which operations are available:

- USB web reads the tablet through its USB web interface and supports reading, rendering, exporting, and uploading.
- Local-directory mode reads the desktop application's sync cache or another xochitl-style directory without requiring a connected tablet. It is offline and read-only.
- Cloud mode uses a registered reMarkable account token and requires a reMarkable Connect subscription. It supports remote access and document or folder management.
- SSH mode connects directly to the tablet over a local or USB connection and provides the broadest management capabilities.

Large reads are paginated by extracted-content page. The read tool can return full text, source PDF or EPUB text, or annotations only, and can restrict the current page with a regular expression. Search can combine document-name matching, content filtering, tags, and optional OCR.

Rendered pages are returned as embedded MCP resources by default. PNG output can merge a PDF underlay with reMarkable annotations; SVG output contains the annotation layer. Clients that cannot handle embedded resources can request a resource URI instead. The canvas tool provides a read-only page viewer, with interactive navigation in clients supporting MCP Apps.

## Setup and configuration

Python 3.11 or later and `uv` are required. The package can be launched with `uvx remarkable-mcp` and a mode argument such as `--usb`, `--local-dir`, or `--ssh`. A minimal cloud or client-neutral configuration uses the command without a mode argument.

Cloud registration starts with a one-time code from reMarkable's device connection page. Running `uvx remarkable-mcp --register YOUR_CODE` saves the resulting credential to `~/.rmapi`; `REMARKABLE_TOKEN` can be used when that file is unavailable. Local-directory mode can auto-detect the desktop application's data directory or accept a custom path.

Enable the tablet's USB web interface for USB mode. SSH mode requires reMarkable developer mode, which factory-resets the tablet when enabled. The server starts with write operations enabled unless launched with `--read-only` or `REMARKABLE_READ_ONLY=1`.

## Tools and capabilities

- Browse folders, search names, filter by tags, and list recent documents.
- Read PDF, EPUB, typed, highlighted, handwritten, and OCR-derived content.
- Render pages as PNG or SVG and open them in a read-only canvas viewer.
- Export complete PDFs or structured Markdown through temporary resource links.
- Upload PDF and EPUB files, or render Markdown directly to a tablet PDF.
- Create, move, rename, and delete documents and folders where the transport supports writes.

## Limitations and notes

Local-directory mode is intentionally read-only because direct changes could corrupt the desktop application's synchronization cache. USB web mode cannot create folders or move, rename, or delete items because the tablet interface does not expose those endpoints; its upload destination is selected by the tablet and ignores the requested parent folder.

Exported resources are temporary, expire after 15 minutes, and may be evicted earlier when more than eight exports are retained. Save a linked resource if it needs to persist. Multi-document search returns at most five documents and the first approximately 8,000 characters from each result.

Older USB firmware may provide only a native PDF. In that case, annotation archives may be unavailable, SVG and explicit annotation-only rendering require an archive, and text extraction can contain source text without annotations. OCR is opt-in for relevant tools. Delete requests require client elicitation support or `REMARKABLE_SKIP_CONFIRM=1` for headless operation.

_Full upstream README: https://allmcps.com/mcp/remarkable-mcp-server/readme_

