remarkable-mcp

🚀 reMarkable MCP 服务器

将你的 reMarkable 平板电脑解锁为人工智能助手的第二大脑。这个 MCP 服务器允许 Claude、VS Code Copilot 等人工智能工具读取、搜索和遍历你整个 reMarkable 文库，包括通过 OCR 识别的手写笔记。

🚀 快速开始

为什么选择 remarkable-mcp？

你的 reMarkable 平板电脑是思考、记笔记和研究的强大工具。但这些知识被困在了设备上。这个 MCP 服务器改变了这一现状：

• 全文库访问 — 浏览文件夹、搜索文档、读取任何文件
• 打字文本提取 — 原生支持 Type Folio 和打字注释
• 手写 OCR — 将手写笔记转换为可搜索的文本
• PDF 和 EPUB 支持 — 从文档中提取文本，以及你的注释
• 智能搜索 — 在整个文库中查找内容
• 第二大脑集成 — 可与 Obsidian、笔记应用程序或任何人工智能工作流程配合使用

无论你是在进行研究、写作还是开发创意，remarkable-mcp 都能让你通过人工智能充分利用 reMarkable 上的所有内容。

⚡ 快速安装

SSH 模式（推荐）

通过 USB 直接连接，实现快 10 - 100 倍的访问速度，支持离线操作，且无需订阅。

要求：启用开发者模式 并通过 USB 连接到你的 reMarkable。

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

☁️ 云模式（替代方案）

如果你无法启用开发者模式，可以使用云 API。需要 reMarkable Connect 订阅。

uvx remarkable-mcp --register YOUR_CODE

{
  "inputs": [
    {
      "type": "promptString",
      "id": "remarkable-token",
      "description": "reMarkable API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "google-vision-key",
      "description": "Google Vision API Key",
      "password": true
    }
  ],
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp"],
      "env": {
        "REMARKABLE_TOKEN": "${input:remarkable-token}",
        "GOOGLE_VISION_API_KEY": "${input:google-vision-key}"
      }
    }
  }
}

✨ 主要特性

工具

| 工具 | 描述 | |------|-------------| | remarkable_read | 读取文档并提取文本（支持分页和搜索） | | remarkable_browse | 浏览文件夹或按文档名称搜索 | | remarkable_search | 在多个文档中搜索内容 | | remarkable_recent | 获取最近修改的文档 | | remarkable_status | 检查连接状态 | | remarkable_image | 获取页面的 PNG/SVG 图像（支持通过采样进行 OCR） |

所有工具均为只读，并返回带有下一步操作提示的结构化 JSON。

📖 完整工具文档

智能特性

• 自动重定向 — 浏览文档路径会自动返回其内容
• 自动 OCR — 没有打字文本的笔记本会自动启用 OCR
• 批量搜索 — 一次调用即可在多个文档中搜索
• 视觉支持 — 获取页面图像以提供视觉上下文（图表、模型、草图）
• 采样 OCR — 使用客户端的人工智能进行图像 OCR（无需 API 密钥）

资源

文档会自动注册为 MCP 资源： | URI 方案 | 描述 | |------------|-------------| | remarkable:///{path}.txt | 提取的文本内容 | | remarkableraw:///{path}.pdf | 原始 PDF 文件（仅 SSH 模式） | | remarkableraw:///{path}.epub | 原始 EPUB 文件（仅 SSH 模式） | | remarkableimg:///{path}.page-{N}.png | 第 N 页的 PNG 图像（仅笔记本） | | remarkablesvg:///{path}.page-{N}.svg | 第 N 页的 SVG 矢量图像（仅笔记本） |

📖 完整资源文档

手写 OCR

对于手写内容，remarkable-mcp 提供了几种 OCR 后端。可根据你的设置和需求进行选择： | 后端 | 设置 | 质量 | 离线 | 最适合 | |---------|-------|---------|---------|----------| | 采样 | 无需 API 密钥 | 取决于客户端模型 | ✅ | 拥有强大人工智能客户端的用户 | | Google Vision | 需要 API 密钥 | 优秀 | ❌ | 追求最佳手写识别准确率 | | Tesseract | 系统安装 | 对手写效果差 | ✅ | 打印文本，离线备用 |

快速设置

在你的 MCP 配置中设置 REMARKABLE_OCR_BACKEND：

{
  "env": {
    "REMARKABLE_OCR_BACKEND": "sampling"
  }
}

选项：sampling、google、tesseract、auto

# 安装 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

SSH 与云模式对比

| 特性 | SSH 模式 | 云 API | |---------|----------|-----------| | 速度 | ⚡ 快 10 - 100 倍 | 较慢 | | 离线 | ✅ 支持 | ❌ 不支持 | | 订阅 | ✅ 无需 | ❌ 需要 Connect 订阅 | | 原始文件 | ✅ 支持 PDFs、EPUBs | ❌ 不可用 | | 设置 | 需要开发者模式 | 需要一次性代码 |

📖 SSH 设置指南

💻 使用示例

基础用法

# 读取文档
remarkable_read("Meeting Notes")

# 搜索关键词
remarkable_read("Project Plan", grep="deadline")

# 为手写笔记启用 OCR
remarkable_read("Journal", include_ocr=True)

# 浏览你的文库
remarkable_browse("/Work/Projects")

# 在多个文档中搜索
remarkable_search("meeting", grep="action items")

# 获取最近的文档
remarkable_recent(limit=10)

# 获取页面图像（用于 UI 模型或图表等视觉内容）
remarkable_image("UI Mockup", page=1)

# 获取 SVG 格式以便在设计工具中编辑
remarkable_image("Wireframe", output_format="svg")

# 获取带有 OCR 文本提取的图像（如果配置了则使用采样）
remarkable_image("Handwritten Notes", include_ocr=True)

# 透明背景以便合成
remarkable_image("Logo Sketch", background="#00000000")

# 兼容模式：返回资源 URI 而不是嵌入式资源
remarkable_image("Diagram", compatibility=True)

📚 详细文档

高级配置

根路径过滤

将 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 之外的文档无法访问

适用于：

• 在办公时间专注于工作文档
• 分离个人和专业笔记
• 为特定的人工智能工作流程限定范围

自定义背景颜色

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

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

支持的格式：

• #RRGGBB — RGB 十六进制（例如，#FFFFFF 表示白色）
• #RRGGBBAA — RGBA 十六进制（例如，#00000000 表示透明）

默认值为 #FBFBFB（reMarkable 纸张颜色）。这会影响 remarkable_image 工具和图像资源。

使用案例

研究与写作

在使用 Obsidian 库或类似工具时使用 remarkable-mcp，将手写笔记中的知识转化为结构化文档。人工智能可以读取你的研究笔记并帮助你拓展思路。

每日回顾

让你的人工智能助手总结你最近的笔记、查找行动项或识别日记条目中的模式。

文档搜索

通过在整个文库中搜索，找到那半记不清的笔记，包括手写内容。

知识管理

将你的 reMarkable 视为人工智能可以访问的第二大脑。结合 Obsidian 等工具，你可以构建强大的个人知识系统。

文档指南

| 指南 | 描述 | |-------|-------------| | 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 test_server.py -v

📖 开发指南

📄 许可证

MIT

本项目基于 rmscene、PyMuPDF 构建，并受到 ddvk/rmapi 的启发。