关于 reMarkable MCP Server
reMarkable MCP Server 是一个 MCP 服务,让 MCP 客户端访问 reMarkable 文档库,可浏览、搜索、读取和渲染文档内容。它支持 USB web、本地目录、云端和 SSH 等多种连接方式,适合希望在 AI 客户端中处理 reMarkable 笔记的用户。
主要功能
- 01浏览文件夹与最近文档
- 02按名称、标签和提取文本搜索
- 03读取文字、PDF/EPUB 文本、高亮和批注
- 04将笔记本渲染为 PNG 或 SVG
- 05导出完整 PDF 或分节 Markdown 资源
- 06支持 stdio 与本地 Streamable HTTP
适用场景
- 01在 AI 客户端中检索历次会议笔记
- 02将带批注的 PDF 渲染为图片供模型分析
- 03把单个文档导出为 Markdown 用于整理
MCP 相关
该项目是 MCP 服务,向 Claude、VS Code Copilot、OpenWebUI 等 MCP 客户端暴露 reMarkable 库的浏览、读取、渲染和导出等工具。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
uvx remarkable-mcpREMARKABLE_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+)。各客户端的配置文件位置不同,请参考客户端文档。
工具
14收录的工具列表 · 更新于 2 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| grep | any | 否 | |
| page | integer | 否 | |
| document | string | 是 | |
| include_ocr | boolean | 否 | |
| content_type | enum | 否 | 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提供 MCP2026-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
选择连接方式
从最适合你配置的第一种模式开始。
| 顺序 | 模式 | 设置 | 写入 | 适用场景 |
|---|---|---|---|---|
| 1 | USB Web | 连接平板设备并启用 USB Web | 上传;由平板设备选择目标位置 | 你希望无需订阅或开发者模式即可完成最简设置 |
| 2 | 本地目录 | 安装桌面应用并登录 | 否 | 你希望从桌面缓存离线读取,无需连接设备 |
| 3 | 云端 | 注册一次;需要 Connect 订阅 | 完整的文档和文件夹管理 | 你需要无线或远程访问 |
| 4 | SSH | 启用开发者模式并配置 SSH | 完整管理和原生创作 | 你需要直接访问文件系统或原生笔迹写入 |
USB Web 界面
通过 USB 连接,并在平板电脑的存储设置中启用 Web 界面。
- 通过 USB 连接 reMarkable
- 在平板电脑上,打开 设置 > 存储 并启用 USB Web 界面
- 点击上方按钮进行安装
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 和 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 Vision | API 密钥 | 否 | 手写识别效果较好 |
| Tesseract | 系统安装 | 是 | 更适合印刷文本 |
快速设置
在 MCP 配置中设置 REMARKABLE_OCR_BACKEND:
{
"env": {
"REMARKABLE_OCR_BACKEND": "auto"
}
}
选项: auto、google、tesseract
Google Cloud Vision
- 启用 Cloud Vision API
- 创建 API 密钥
- 在配置中添加:
"GOOGLE_VISION_API_KEY": "your-key"
费用: 每月 1,000 次免费请求,之后每 1,000 次约 1.50 美元。
Tesseract
这是一款面向印刷文本的开源 OCR 工具。手写识别效果较差,但可用作离线备用方案。
# Install Tesseract
# macOS
brew install tesseract
# Ubuntu/Debian
sudo apt install tesseract-ocr
# Windows
choco install tesseract
默认行为(auto)
当 REMARKABLE_OCR_BACKEND=auto(默认值)时:
- Google Vision(如果已设置
GOOGLE_VISION_API_KEY) - 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_ATTEMPTS | 3 | 请求的最大尝试次数(最少为 1) |
REMARKABLE_RETRY_DELAY | 2.0 | 指数退避的基础延迟时间(秒) |
速率限制重试会遵循数值形式和 HTTP 日期形式的 Retry-After 值,上限为
20 秒。身份验证失败会触发令牌续期,而不是重试。
云端性能与缓存
云端模式旨在让无需设备的工作流运行得更快:
- 并行遍历:并发获取文档元数据。
- 连接池:重用 HTTP 连接。
- 内容寻址的 Blob 缓存:按哈希重用不可变 Blob,并在文档发生变化时获取新的哈希。
通常无需配置这些选项,但可以通过以下环境变量进行调整:
| 变量 | 默认值 | 描述 |
|---|---|---|
REMARKABLE_SYNC_WORKERS | 16 | 云端获取任务的并行工作线程数(上限为 64)。 |
REMARKABLE_DISABLE_CACHE | 未设置 | 设为 1 可完全禁用磁盘上的 Blob 缓存。 |
REMARKABLE_CACHE_DIR | ~/.remarkable/cache/blobs | 缓存 Blob 的存储位置。 |
REMARKABLE_CACHE_MAX_BLOB | 4194304 (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 中汲取灵感。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。