内容
# remarkable-mcp
从 AI 助手使用您的 reMarkable 库。
要求它查找笔记本，显示一页，上传 PDF 或整理文件夹。`remarkable-mcp` 直接连接到 reMarkable Cloud，并保持每次响应足够小，以便作为模型上下文。
> 仅限云端，因为这是我使用的唯一 reMarkable 工作流。
## 设计意图
主要目标是将 reMarkable 页面作为图像有效载荷传递给支持视觉的编码代理。OCR 最终是对页面的有损压缩：它会丢弃手写字符、布局、图表以及注释与源材料之间的关系。保留页面视觉效果可以为模型保留这些信息。
令牌效率也很重要。读取操作每次返回一个有界图像， discovery 工具返回简短的分页结果，管理工具在可能的情况下会用一个简洁的确认答案。
## 快速入门
### 1. 安装
Linux 或 macOS：
```bash
curl -fsSL https://raw.githubusercontent.com/Bradley-Butcher/remarkable-mcp/main/install.sh | bash
```
这将最新验证的版本安装到 `~/.local/bin`。Windows 用户可以从 [GitHub Releases](https://github.com/Bradley-Butcher/remarkable-mcp/releases) 下载 `.zip` 文件。
如果安装后找不到 `remarkable-mcp`，请将安装目录添加到您的 `PATH` 中，然后重启您的 MCP 客户端。
### 2. 将其添加到您的 MCP 客户端
使用 `remarkable-mcp` 作为本地 stdio 服务器。常见的配置格式是：
```json
{
"mcpServers": {
"remarkable": {
"command": "remarkable-mcp"
}
}
}
```
您的客户端可能会使用不同的外部键或设置屏幕，但命令保持不变。
### 3. 连接您的帐户
重启您的 MCP 客户端，然后告诉您的助手：
> 连接到我的 reMarkable。
官方 reMarkable 连接页面将在您的浏览器中打开。粘贴一次性代码到对话中。当服务器用设备令牌交换它并本地存储令牌时；代码和令牌永远不会返回给模型。
您现在可以要求：
> 显示我最近的笔记。
## 试试看
```text
显示我最近的 10 个 reMarkable 文档。
浏览 /Work/Meetings 文件夹。
在我的 reMarkable 中搜索“启动计划”。
显示 /Work/Meetings/Launch review 的第 3 页。
放大该页的右下四分之一。
将 ./papers/attention.pdf 上传到 /Reading。
创建 /Work/Archive 并将旧规划笔记移动到那里。
将 /Scratch/Unused 移动到回收站。
```
完整路径在两个文档共享一个名称时最好用。页码是从 1 开始的。
## 助手可以执行的操作
| 工具 | 执行操作 |
|---|---|
| `remarkable_connect` | 打开官方连接页面或使用一次性代码完成连接。 |
| `remarkable_read` | 返回一个页面为一个有边界的 JPEG，带有可选的裁剪和详细级别。 |
| `remarkable_browse` | 一次列出一个文件夹。 |
| `remarkable_search` | 搜索文档名称、路径和标签。 |
| `remarkable_recent` | 列出最近修改的文档。 |
| `remarkable_status` | 检查云连接。 |
| `remarkable_upload` | 上传一个本地 PDF 或 EPUB，最大 512 MiB。 |
| `remarkable_mkdir` | 创建一个文件夹。 |
| `remarkable_move` | 移动文档或文件夹。 |
| `remarkable_rename` | 重命名文档或文件夹。 |
| `remarkable_delete` | 将文档或文件夹移动到云回收站。 |
故意没有单独的图像、画布、OCR 或批量导出工具。
## 页面图像
`remarkable_read` 始终返回一个图像和一个短页面标签。
- 标准：长边最多 1600 像素，1 MiB。
- 高细节：最多 2048 像素，1.5 MiB。
- 裁剪使用归一化页面坐标，并在调整大小之前以额外分辨率渲染。
- PDF 页面在本地栅格化；reMarkable 墨水复合在页面上。
- 笔记本墨水被解析并在本地渲染。
服务器不运行 OCR。手写体仍然是视觉的，搜索不检查手写单词。EPUB 页面元数据和墨水可以渲染，但 EPUB 文本底层不会在本地布局。
## 隐私和凭证
- 云请求直接从此服务器到 reMarkable。
- 连接流程使用 [reMarkable 的官方设备页面](https://my.remarkable.com/device/desktop/connect)。
- 令牌存储在您的平台配置目录中，并设置为 Unix 上的所有者权限。
- 您可以使用 `REMARKABLE_TOKEN` 提供设备令牌，而不是存储在磁盘上。
- 工具错误很短，永远不包括连接代码或令牌。
## 安装选项
安装特定版本：
```bash
curl -fsSL https://raw.githubusercontent.com/Bradley-Butcher/remarkable-mcp/main/install.sh -o install-remarkable-mcp.sh
bash install-remarkable-mcp.sh v0.1.0
```
选择另一个安装目录：
```bash
REMARKABLE_MCP_INSTALL_DIR="$HOME/bin" bash install-remarkable-mcp.sh
```
使用 Rust 1.88 或更高版本从源代码构建：
```bash
git clone https://github.com/Bradley-Butcher/remarkable-mcp.git
cd remarkable-mcp
cargo build --release --locked
```
二进制文件位于 `target/release/remarkable-mcp`。
## 故障排除
**服务器命令未找到**
确保 `~/.local/bin` 在 `PATH` 中，然后完全重启 MCP 客户端。您还可以在客户端配置中使用二进制文件的绝对路径。
**连接代码被拒绝**
一次性代码过期。要求助手再次连接，生成新的代码，并在没有周围文本的情况下粘贴。
**文档名称不明确**
浏览后，使用服务器返回的完整库路径。
**EPUB 页面没有文本底层**
EPUB 布局由平板电脑生成，不会由本地渲染器复制。PDF 和笔记本页面具有更完整的视觉支持。
## 开发和发布
```bash
cargo fmt --all -- --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
```
推送 `vX.Y.Z` 标签会运行发布工作流程。测试必须在 Linux、macOS 和 Windows 存档及 SHA-256 校验和附加到发布之前通过。
## 项目状态
该项目使用 reMarkable 未公开的云同步协议，该协议可能会在未经通知的情况下更改。它与 reMarkable AS 无关，也不获得其认可。
在 [MIT License](LICENSE) 下许可。
