mcpField
R
reMarkable MCP Server

reMarkable MCP Server

本地服务
github.com/SamMorrowDrums生产力2584 周前更新

关于 reMarkable MCP Server

reMarkable MCP Server 是一个 MCP 服务,让 MCP 客户端访问 reMarkable 文档库,可浏览、搜索、读取和渲染文档内容。它支持 USB web、本地目录、云端和 SSH 等多种连接方式,适合希望在 AI 客户端中处理 reMarkable 笔记的用户。

主要功能

  1. 01浏览文件夹与最近文档
  2. 02按名称、标签和提取文本搜索
  3. 03读取文字、PDF/EPUB 文本、高亮和批注
  4. 04将笔记本渲染为 PNG 或 SVG
  5. 05导出完整 PDF 或分节 Markdown 资源
  6. 06支持 stdio 与本地 Streamable HTTP

适用场景

  1. 01在 AI 客户端中检索历次会议笔记
  2. 02将带批注的 PDF 渲染为图片供模型分析
  3. 03把单个文档导出为 Markdown 用于整理

MCP 相关

该项目是 MCP 服务,向 Claude、VS Code Copilot、OpenWebUI 等 MCP 客户端暴露 reMarkable 库的浏览、读取、渲染和导出等工具。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"sammorrowdrums-remarkable": {
"command": "uvx",
"args": [
"remarkable-mcp"
],
"env": {
"REMARKABLE_TOKEN": "<REMARKABLE_TOKEN>"
}
}
}
}
启动命令uvx remarkable-mcp
需要配置的环境变量
REMARKABLE_TOKEN密钥Optional cloud credential. Prefer `remarkable-mcp --register CODE`, which saves it to ~/.rmapi. USB, SSH, and local-directory modes do not require it.

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
pypiremarkable-mcp2.1.0

工具

14

收录的工具列表 · 更新于 2 周前

参数类型必填说明
grepany否
pageinteger否
documentstring是
include_ocrboolean否
content_typeenum否text | raw | annotations

详细介绍

reMarkable MCP 服务

通过 Claude、VS Code Copilot、OpenWebUI 和其他兼容工具等 MCP 客户端访问 reMarkable 文库。

功能

  • 浏览文件夹和最近的文档。
  • 搜索名称、标签和提取的文本。
  • 阅读键入的文本、PDF 和 EPUB 文本、高亮内容及批注。
  • 将笔记本和带批注的 PDF 渲染为 PNG 或 SVG。
  • 将单个文档导出为完整 PDF 或分节 Markdown 资源。
  • 通过 Google Vision 或 Tesseract 执行手写 OCR。
  • 在受支持的传输方式中上传文件并管理文件夹。
  • 将 Markdown 渲染为 PDF 并上传到平板设备。
  • 在支持 MCP Apps 的客户端中打开交互式画布。
  • 通过 stdio 或本地 Streamable HTTP 提供 MCP 服务。
  • 通过一个稳定的 SDK 2.x MCPServer 提供 MCP 2026-07-28 及所有更早的 SDK 支持版本。

快速安装

前提条件:安装 uv

以下命令使用 uvx,它包含在 uv 中。 页面图像使用 PyMuPDF 栅格化;在 macOS、Linux 或 Windows 上,无需安装系统 Cairo、浏览器或图形运行时。

macOS 和 Linux

使用官方独立安装程序:

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

或者使用 Homebrew 安装:

brew install uv
Windows

在 PowerShell 中使用官方独立安装程序:

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

或者使用 WinGet 安装:

winget install --id=astral-sh.uv -e
选择连接方式

从最适合你配置的第一种模式开始。

顺序模式设置写入适用场景
1USB Web连接平板设备并启用 USB Web上传;由平板设备选择目标位置你希望无需订阅或开发者模式即可完成最简设置
2本地目录安装桌面应用并登录否你希望从桌面缓存离线读取,无需连接设备
3云端注册一次;需要 Connect 订阅完整的文档和文件夹管理你需要无线或远程访问
4SSH启用开发者模式并配置 SSH完整管理和原生创作你需要直接访问文件系统或原生笔迹写入
USB Web 界面

通过 USB 连接,并在平板电脑的存储设置中启用 Web 界面。

在 VS Code 中安装 USB Web 模式 在 VS Code Insiders 中安装 USB Web 模式

  1. 通过 USB 连接 reMarkable
  2. 在平板电脑上,打开 设置 > 存储 并启用 USB Web 界面
  3. 点击上方按钮进行安装
USB Web 手动配置

添加到 .vscode/mcp.json:

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--usb"],
      "env": {
        "GOOGLE_VISION_API_KEY": "your-api-key"
      }
    }
  }
}
  • 确保 reMarkable 已通过 USB 连接并解锁
  • 确认已在“设置 > 存储”中启用 USB Web 界面
  • 平板电脑应可通过 http://10.11.99.1 访问

本地目录模式

从磁盘读取官方 reMarkable 桌面应用的同步文件夹。此模式为 离线且只读。同步由桌面应用控制。

本地目录配置

添加到 .vscode/mcp.json:

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

如果未指定路径,将自动检测桌面应用的数据文件夹:

  • macOS(当前应用): ~/Library/Containers/com.remarkable.desktop/Data/Library/Application Support/remarkable/desktop
  • macOS(旧版应用): ~/Library/Application Support/remarkable/desktop
  • Windows: %APPDATA%\remarkable\desktop
  • Linux: ~/.local/share/remarkable/desktop

或者指定任意 xochitl 风格的目录(例如平板电脑备份):

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--local-dir", "/path/to/xochitl-data"]
    }
  }
}
  • 内容的新鲜度取决于桌面应用。请保持应用运行并登录。
  • 此模式为只读。直接写入可能绕过同步并损坏应用缓存。
  • 如果找不到目录且已配置云令牌,服务将回退到云模式以进行读取(由于服务以本地目录模式启动,因此仍为只读)

云模式

云模式无需连接设备即可使用,但需要订阅 reMarkable Connect。

它会并行获取元数据,并在磁盘上缓存内容寻址的 Blob。配置请参阅 云模式性能与缓存。

云模式设置
1. 获取一次性代码

前往 my.remarkable.com/device/desktop/connect 并生成代码。

2. 转换为令牌
uvx remarkable-mcp --register YOUR_CODE

注册后,令牌将保存到 ~/.rmapi。当你的 MCP 客户端在同一台机器上以同一用户身份运行服务时,remarkable-mcp 会自动读取该文件,因此无需在客户端配置中填写令牌。仅当 ~/.rmapi 不可用时才设置 REMARKABLE_TOKEN,例如服务以其他用户身份运行或在另一台机器上运行时。

3. 配置 MCP 客户端
精简且与客户端无关的服务定义

使用客户端所需的 MCP 配置 UI 或包装器添加此服务定义:

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

如果服务可以从 ~/.rmapi 读取令牌,则无需添加 env 条目。

VS Code

VS Code 的 .vscode/mcp.json 使用顶层 servers 对象。已保存的 ~/.rmapi 凭据意味着无需输入令牌:

{
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp"]
    }
  }
}
Claude Desktop 和其他客户端

Claude Desktop 和许多其他 MCP 客户端使用顶层 mcpServers 对象以及 env 中的字面值;它们不使用 VS Code 的 inputs 数组。令牌已存于 ~/.rmapi 时,最精简的配置为:

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

如果令牌文件不可用,请在 remarkable 服务条目中添加 "env": {"REMARKABLE_TOKEN": "your-token"}。如果客户端使用不同的外层键或机密存储机制,请参阅其文档。


SSH 模式

SSH 可提供直接的文件系统访问和原生笔记本创作功能。此模式需要 开发者模式,启用时会将平板恢复出厂设置。 只有当 USB Web、本地目录或云模式无法满足所需操作时,才使用此模式。

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

有关身份验证和设备设置,请参阅 SSH 设置指南。



连接模式

所有模式均支持读取、渲染和导出单个文档。云模式和 SSH 支持完整的文库 管理。USB Web 支持上传,但不接受目标文件夹。 本地目录模式为 只读。

模式设置订阅离线需要平板原始源文件上传文件夹操作¹
本地目录已安装桌面应用否²是否PDF 和 EPUB否否
USB Web在设置中启用否是是PDF仅根目录否
云一次性注册连接否否PDF 和 EPUB是是
SSH开发者模式否是是PDF 和 EPUB是是

¹ 文件夹操作 = 创建文件夹 / 移动 / 重命名 / 删除。上传和文件夹操作默认启用;传入 --read-only 可启动只读服务。删除会将项目移至回收站;当客户端支持请求确认时,会提示确认。如果客户端不支持请求确认,则拒绝删除,除非设置了 REMARKABLE_SKIP_CONFIRM=1。

² 桌面应用本身会登录 reMarkable 云以进行同步;本地目录模式只读取应用已同步到磁盘的内容。

自动回退到云模式

如果所选设备传输方式不可用且已配置云凭据,服务将回退到云模式。使用 --local-dir 启动的服务在回退后仍为只读。remarkable_status 会报告实际使用的传输方式,并设置 fell_back_to_cloud。

传入 --no-cloud-fallback(或设置 REMARKABLE_DISABLE_CLOUD_FALLBACK=1)可禁用此功能,并在设备无法连接时改为失败退出。

每个服务进程只解析一次传输方式。如果进程已回退到云模式,连接设备或启动桌面应用后,请重启 MCP 服务。

详细设置:


OpenWebUI(Streamable HTTP)

OpenWebUI 原生的 MCP 连接使用 Streamable HTTP。在同一台机器上启动 remarkable-mcp:

uvx remarkable-mcp --http

然后在 OpenWebUI 中将 http://127.0.0.1:8000/mcp 添加为 MCP 服务 URL。HTTP 传输可与 --usb、--ssh 和 --read-only 搭配使用;例如:

uvx remarkable-mcp --usb --http

还可以通过 --host / --port 或 REMARKABLE_MCP_HOST / REMARKABLE_MCP_PORT 设置绑定地址和端口。

该服务使用 MCP Python SDK 2.x 的双时代端点。现代的 2026-07-28 请求无需会话;较旧的客户端仍会在同一 /mcp 路由上使用 initialize 握手和旧版 MCP 会话。reMarkable 令牌和所选平板电脑传输方式仍通过进程本地的 CLI/env 配置设置,绝不会从 MCP HTTP 授权标头推断。

警告

Streamable HTTP 没有内置身份验证。默认绑定到 127.0.0.1。除非你能控制网络边界,否则请保留此默认设置。拒绝 0.0.0.0 和 :: 等通配符绑定,因为它们无法提供严格的 Host 允许列表。允许使用具体的非环回地址,但能访问该端口的客户端将可访问所有已启用的工具,包括写入工具。

通过经过身份验证的反向代理进行远程访问

让 remarkable-mcp 保持默认的环回绑定,并在同一主机上运行代理。MCPServer 的 DNS 重绑定防护默认只允许环回 Host 和 Origin 值。因此,原样转发公共主机名的代理会收到 421 Misdirected Request;公共浏览器 Origin 则会收到 403 Forbidden。

代理必须对请求进行身份验证,将 Host 重写为环回上游,并清除 Origin。例如,使用 nginx 和现有的 htpasswd 文件:

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 "";
}

请勿直接公开上游端口。为 OpenWebUI 配置经过身份验证的代理 URL,例如 https://mcp.example.com/mcp。

对于 NixOS,remarkable-mcp-bridge.nix 提供了一个具有相同环回默认设置的 systemd 模块:

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

服务用户必须在 /var/lib/remarkable-mcp(或配置的 home)下保存其 reMarkable 凭据。该模块会将 Tesseract 添加到服务的可执行文件搜索路径中;请单独安装已配置的 command。


OpenClaw 集成

remarkable-mcp 可作为 OpenClaw 技能使用。将以下内容添加到你的 openclaw.json:

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

从 ClawHub 安装:

clawhub install remarkable-mcp

或者将此仓库中的 SKILL.md 复制到你的 ~/.openclaw/skills/remarkable-mcp/ 目录。


工具

工具描述
remarkable_read从文档中读取并提取文本(支持分页和搜索)
remarkable_browse浏览文件夹、按文档名称搜索或按标签筛选
remarkable_search搜索多个文档中的内容(支持按标签筛选)
remarkable_recent获取最近修改的文档
remarkable_status检查连接状态和各传输方式的功能矩阵
remarkable_image获取页面的 PNG/SVG 图像,可选进行 OCR
remarkable_export将单个文档导出为临时 PDF 或 Markdown 资源

读取、搜索和渲染工具均为只读。remarkable_export 不会更改平板电脑,但会在 MCP 服务主机上写入有大小限制的临时文件,因此声明 readOnlyHint=false。导出链接会在 15 分钟后过期,服务最多保留八个链接。 支持的传输方式默认也会注册写入工具;传入 --read-only 可将其禁用。请参阅写入工具(按传输方式)。支持 MCP Apps 的客户端也可以打开 remarkable_canvas。

完整工具参考

工具行为
  • 浏览文档路径会返回其内容。
  • 笔记本的文本为空时,可以自动触发 OCR。
  • 搜索可扫描多个匹配的文档。
  • 图像工具会返回文本提取无法识别的视觉内容。
  • remarkable_read.total_pages 是文档的实际页数;content_pages 表示提取文本块的数量,后续文本块可通过 more / next_page 获取。 原始 PDF 读取会统计已下载 PDF 的页数。如果无法读取原始 EPUB 的独立存档, 仍会返回其文本,但 total_pages: null 且 total_pages_known: false。
  • PDF 页面对应的 PNG 图像会自动合并源页面和批注;传入 render_merged=False 可仅返回批注层。
  • PDF 导出会保留实际页面顺序,并默认将映射的源页面底图与批注合并。Markdown 导出会保留固定的源内容/手写内容/批注/高亮/OCR 分区,不会推测文档结构。
  • 配置后,OCR 会使用 Google Vision;否则会在本地使用 Tesseract 运行。
  • 浏览和搜索支持标签筛选。
使用示例
# 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")

注意: PNG 渲染对笔记本 SVG 和 PDF 页面都使用 PyMuPDF,因此 remarkable_image 不需要 Cairo、Inkscape、Chromium 或其他系统图形运行时。 如果本地笔画解析无法处理某个页面,USB 和 SSH 模式会回退到平板电脑的原生 PDF 导出;云模式则会在存在原始源 PDF 时 回退到该文件。


资源

文档会自动注册为 MCP 资源:

URI 方案说明
remarkable:///{path}.txt提取的文本内容
remarkableraw:///{path}.pdf.txt从原始 PDF 中提取的文本
remarkableraw:///{path}.epub.txt从原始 EPUB 中提取的文本
remarkableimg:///{path}.page-{N}.png第 N 页的 PNG 图像(仅限笔记本)
remarkablesvg:///{path}.page-{N}.svg第 N 页的 SVG 矢量图像(仅限笔记本)
remarkableexport:///{format}/{id}临时生成的 PDF 或 Markdown 导出文件

已移至回收站的文档不会纳入工具、画布和资源查找,因此同名的回收站项目不会遮蔽有效文档。

remarkable_export 会返回 ResourceLink,而不会在工具响应中嵌入可能很大的文件内容。服务会将文件存储在私有临时目录中 15 分钟,最多保留 8 个导出文件,并在关闭时删除受其管理的导出文件。请获取并保存链接资源,以便长期使用。

完整资源参考


手写内容的 OCR

对于手写内容,remarkable-mcp 提供两种 OCR 后端:

后端设置离线备注
Google VisionAPI 密钥否手写识别效果较好
Tesseract系统安装是更适合印刷文本
快速设置

在 MCP 配置中设置 REMARKABLE_OCR_BACKEND:

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

选项: auto、google、tesseract

Google Cloud Vision
  1. 启用 Cloud Vision API
  2. 创建 API 密钥
  3. 在配置中添加:"GOOGLE_VISION_API_KEY": "your-key"

费用: 每月 1,000 次免费请求,之后每 1,000 次约 1.50 美元。

Google Vision 设置指南

Tesseract

这是一款面向印刷文本的开源 OCR 工具。手写识别效果较差,但可用作离线备用方案。

# Install Tesseract
# macOS
brew install tesseract

# Ubuntu/Debian
sudo apt install tesseract-ocr

# Windows
choco install tesseract
默认行为(auto)

当 REMARKABLE_OCR_BACKEND=auto(默认值)时:

  1. Google Vision(如果已设置 GOOGLE_VISION_API_KEY)
  2. Tesseract(备用方案)

按传输方式划分的写入工具

写入工具可让你在 reMarkable 上上传、整理和管理文档。**在支持写入的传输方式中默认启用。**云端和 SSH 模式支持完整功能;USB Web 仅支持上传(其固件不提供文件夹操作);本地目录模式始终为只读。在其他模式下,可传入 --read-only 以启用只读服务。

功能本地目录云端模式SSH 模式USB Web 模式
上传❌✅✅✅(由平板选择文件夹)
创建文件夹❌✅✅❌
移动❌✅✅❌
重命名❌✅✅❌
删除❌✅(→ 垃圾箱)✅(→ 垃圾箱;可选永久删除)❌
禁用写入工具(只读模式)

在每种支持写入的模式中,写入工具默认开启。本地目录模式始终为只读。若要将其他传输方式设为只读,请添加 --read-only 标志:

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

它可以与任何传输方式标志(--ssh、--usb)组合使用:

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

或者设置环境变量:

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

为保持向后兼容,仍接受旧版 --write 标志和 REMARKABLE_ENABLE_WRITE 变量,但它们现在不执行任何操作(写入功能默认开启)。--write 和 --read-only 不能同时使用。

可用的写入工具
工具描述
remarkable_upload(file_path, parent_folder, document_name, defer_restart)上传 PDF 或 EPUB 文件(云端、SSH 和 USB Web;USB Web 保留名称,但忽略 parent_folder)
remarkable_markdown_to_pdf(markdown, document_name, parent_folder, defer_restart)将 Markdown 渲染为分页 PDF 并上传(云端、SSH 和 USB Web)
remarkable_mkdir(folder_name, parent, defer_restart)创建新文件夹(云端和 SSH)
remarkable_move(document, dest_folder, defer_restart)移动文档或文件夹(云端和 SSH)
remarkable_rename(document, new_name, defer_restart)重命名文档或文件夹(云端和 SSH)
remarkable_delete(document, defer_restart, permanent)将文档/文件夹移至垃圾箱;SSH 可通过 permanent=True 永久删除
remarkable_refresh()安全地重启一次 xochitl,以应用使用 defer_restart=True 执行的待处理写入;此进程确认状态干净后,此操作不执行任何操作 — 仅限 SSH
remarkable_author(method, ..., defer_restart)创作原生墨迹和笔记本 — draw(追加笔迹)、add_page(在笔记本末尾添加空白页)、create_document(新建笔记本)— 仅限 SSH
安全性
  • 云端、SSH 和 USB Web 模式下可用上传工具 — 本地目录模式绝不公开写入工具。
  • mkdir、移动、重命名和删除工具仅在云端和 SSH 模式下可用 — USB Web 模式不会公开这些工具(平板的 USB Web 固件没有文件夹/移动/重命名/删除端点),确保工具列表仅包含当前传输方式实际支持的工具。
  • 尽可能在删除前请求确认 — 如果客户端支持 MCP elicitation,remarkable_delete 会在删除前请求用户确认。对于 2026-07-28 客户端,MCP SDK 2.x 会将此提示作为多轮输入请求传递;对于旧版客户端,则作为推送式 elicitation 传递。如果客户端无法显示提示,则会拒绝删除(不会执行),除非设置了 REMARKABLE_SKIP_CONFIRM=1 — 这样,默认启用写入的客户端若不支持 elicitation,也无法静默删除。云端和 SSH 默认会将项目移至废纸篓。SSH 还支持 permanent=True,用于明确请求永久删除;云端永久删除仍需在应用/平板中通过废纸篓管理操作完成。在自动化设置中,可设置 REMARKABLE_SKIP_CONFIRM=1,允许无需提示即可删除。所有写入工具都带有 ToolAnnotations(read_only_hint=False)(删除工具还带有 destructive_hint=True),以便 Agent 执行框架能在 MCP 层控制写入操作。
  • SSH 操作在每台服务上公平排队并串行执行 — 单个 FIFO 分发器负责所有 SSH 子进程,因此启动扫描、读取、上传、修改和刷新探测不会并发占用平板的 USB CDC 连接。缓存的元数据读取不经过队列。
  • 并发 SSH 写入共用刷新屏障 — 几乎同时发生的写入会按 FIFO 顺序持久化,然后每个参与调用都会等待一次共用的 xochitl 重启后再报告成功。有限时长的防抖会合并突发请求,不会产生后台或延迟成功。
  • SSH 刷新会避开固件的紧急重启路径 — 串行刷新会在重启前立即清除 xochitl 的 systemd 启动计数器,然后要求同一启动周期内的 SSH 会话保持稳定且不复用。OpenSSH 别名会通过 ssh -G 解析;如果重启前该有效主机可通过 USB Web 访问,则端口 80 也必须恢复。探测失败时会保留 refresh_pending: true,且绝不会重放写入操作。
  • 重试范围刻意保持有限 — 仅对能证明远程命令尚未启动的连接故障(例如连接被拒绝、连接超时或横幅超时)进行有界指数退避。对于有歧义或命令启动后的写入故障,绝不会重放;错误会指示调用方刷新并检查平板。
  • 对于明确的批量操作,请为每次写入(包括 remarkable_author)传入 defer_restart=True — 或设置 REMARKABLE_DEFER_RESTART=1 — 并在最后调用一次 remarkable_refresh()。延迟刷新的写入会立即返回 refresh_pending: true;只有在当前服务进程确认状态干净后,额外的刷新才会变成空操作。新进程会执行一次保守的恢复刷新,因为它无法判断先前进程是否留下了尚未刷新的磁盘更改。
  • 如果多步骤 SSH 写入在确认发生任何修改后失败,则会返回 write_partially_persisted,说明不要重复,并报告刷新恢复是否仍待处理。共用刷新失败只会传播给自身修改已产生变更的参与者;验证/执行前失败且未产生变更的操作会保留原始错误。
  • USB HTTP 请求使用相同的有界操作核心,并受 REMARKABLE_USB_MAX_CONCURRENCY 控制(默认值为 2)。云同步保留现有的连接池式、支持幂等性的请求层,并由 REMARKABLE_SYNC_WORKERS 控制。
示例
# 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")

交互式画布应用(MCP Apps)

基于 MCP Apps 扩展(SEP-1865)构建的交互式页面查看器。支持 MCP Apps 的客户端(例如 ChatGPT、Claude、VS Code 和 MCP Inspector)会在侧边栏中渲染画布,供你查看文档页面并浏览文档。

无需启用任何标志——remarkable_canvas 工具及其 ui://remarkable/canvas 资源始终处于注册状态,并且客户端能力会自动协商(通过现代发现机制或传统的 initialize 握手)。支持应用的客户端会打开交互式画布;其他所有客户端只会收到渲染后的页面图像,因此该工具在任何客户端中都安全且实用。

这会注册一个工具:

工具说明
remarkable_canvas(document, page)在交互式画布查看器中打开一个页面

行为如下:

  • 支持应用的客户端会打开画布(声明于 ui://remarkable/canvas,MIME 类型为 text/html;profile=mcp-app),并可通过 MCP Apps 的 postMessage 桥接浏览文档页面——服务端会在协议结果的 structuredContent 中提供每个渲染后的页面(在 Python 中为 structured_content)。
  • 其他客户端仍会收到作为嵌入式 PNG 图像返回的渲染页面,因此该工具在任何客户端中都实用;只是不会打开交互式面板。对于未声明支持 MCP Apps UI 扩展的客户端,_meta.ui / ui:// 元数据不会生效。
在画布中绘图和创作

当写入模式开启(默认状态)且当前传输方式为 SSH 时,画布会变为可写入界面:

  • 绘图:选择钢笔或荧光笔,绘图,然后将原生 .rm 笔迹保存到设备。
  • 添加页面:排入一个空白的原生笔记本页面,进行绘图,然后保存。
  • 唯一事实来源:画布会调用模型也会调用的同一个 remarkable_author 工具(点击 Save 时使用 method="draw",点击 +Page 时使用 method="add_page"),因此人工操作路径和模型操作路径生成的结果逐字节完全一致。

当页面不可写入时(只读模式或使用非 SSH 传输方式),Save / Draw / +Page 控件会隐藏,画布则会退回到普通图片查看器。iframe 桥接遵循 MCP Apps 规范,但最好针对你使用的特定客户端进行验证。


高级配置

根路径筛选

将 MCP 服务限制在 reMarkable 上的特定文件夹中。所有操作都将限定在此文件夹内:

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

使用此配置后:

  • remarkable_browse("/") 会显示 /Work 的内容
  • remarkable_browse("/Projects") 会显示 /Work/Projects
  • 无法访问 /Work 以外的文档

适用于:

  • 办公时间内专注处理工作文档
  • 分开管理个人笔记和工作笔记
  • 限制特定 AI 工作流的范围
自定义背景色

设置图像渲染的默认背景色:

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

支持的格式:

  • #RRGGBB:RGB 十六进制值,例如 #FFFFFF
  • #RRGGBBAA:RGBA 十六进制值,例如 #00000000

默认值为 #FBFBFB(reMarkable 纸张颜色)。此设置会同时影响 remarkable_image 工具和图像资源。


重试配置

云 API 请求遇到暂时性故障(HTTP 429、500、502、503、504)和网络错误时,会自动采用带抖动的指数退避策略重试。你可以通过环境变量调整此设置:

变量默认值说明
REMARKABLE_RETRY_ATTEMPTS3请求的最大尝试次数(最少为 1)
REMARKABLE_RETRY_DELAY2.0指数退避的基础延迟时间(秒)

速率限制重试会遵循数值形式和 HTTP 日期形式的 Retry-After 值,上限为 20 秒。身份验证失败会触发令牌续期,而不是重试。


云端性能与缓存

云端模式旨在让无需设备的工作流运行得更快:

  • 并行遍历:并发获取文档元数据。
  • 连接池:重用 HTTP 连接。
  • 内容寻址的 Blob 缓存:按哈希重用不可变 Blob,并在文档发生变化时获取新的哈希。

通常无需配置这些选项,但可以通过以下环境变量进行调整:

变量默认值描述
REMARKABLE_SYNC_WORKERS16云端获取任务的并行工作线程数(上限为 64)。
REMARKABLE_DISABLE_CACHE未设置设为 1 可完全禁用磁盘上的 Blob 缓存。
REMARKABLE_CACHE_DIR~/.remarkable/cache/blobs缓存 Blob 的存储位置。
REMARKABLE_CACHE_MAX_BLOB4194304 (4 MiB)大于此值的 Blob 会以流式方式传输,但不会缓存。

缓存只是本地加速机制:删除 REMARKABLE_CACHE_DIR 只会导致下次读取时重新下载。可变的云端根哈希始终会实时获取,因此你不会看到过时的文档库。


常见工作流

  • 阅读近期笔记并提取待办事项。
  • 搜索姓名、标签、键入的文本和 OCR 输出。
  • 同时查看带批注 PDF 的源页面和批注。
  • 将选定的笔记移入另一个本地工作流。
  • 上传参考 PDF 或生成的 Markdown 文档。

文档

指南描述
SSH 设置启用开发者模式并配置 SSH
Google Vision 设置设置手写 OCR
工具参考工具详细文档
资源参考MCP 资源文档
能力协商MCP 协议能力
开发贡献指南和开发环境设置
未来计划路线图和计划中的功能

开发

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

开发指南

Dependabot 通过 uv 生态系统每周检查 Python 依赖项和 uv.lock, 以及 GitHub Actions。依赖项更新会通过 pip-audit 审核; 完整的更新和验证命令请参阅开发指南。

多传输冒烟测试

如果发现问题,首先运行确定性、无需 AI 的冒烟测试。它会通过 MCP 驱动真实服务,并按以下顺序测试每种可用传输方式中所有可用的工具:本地目录、云端、USB Web,然后是 SSH。

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

冒烟测试指南 以及各模式的预期行为。


许可证

MIT


基于 rmscene、 PyMuPDF、 markdown-it-py 构建, 并从 ddvk/rmapi 中汲取灵感。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。