reMarkable USB MCP

An independent Python module and standard MCP stdio server for read-only reMarkable access on Windows10/11. Reading applications can use the Python API directly; MCP hosts can use the same connection logic through three tools.

What it does

The device library is read-only. The module does not change network settings, restart device services, upload documents, remove documents or execute model-supplied commands. Exports preserve the original members; this module does not decode handwriting, reconstruct annotated PDFs or certify rendering fidelity.

Related MCP server: reMarkable MCP Server

USB-only transport

Before every SSH operation, the module discovers active adapters whose Plug-and-Play identity is USB and selects an address on the device's subnet. Discovery is independent of the system's default route and other active network connections. If no unique usable USB address is available, it stops before opening SSH.

The OpenSSH bridge checks the USB address again, binds the source address and sets Windows IP_UNICAST_IF to the selected USB interface. All device traffic stays on that interface, with no alternate transport or automatic retry. Existing SSH configuration is bypassed; host-key validation is strict and uses only the operator's preverified known-hosts file. Private key bytes are read by OpenSSH, not by the Python module.

The standard device target is 10.11.99.1:22. This release intentionally supports Windows only; other operating systems stop rather than silently weakening interface binding. It does not install software on the tablet. SSH/developer access and USB networking must already be configured on the device.

Install and configure

Requires Python3.11+, Windows PowerShell and Windows OpenSSH Client. The Python package uses the official MCP Python SDK2.x. Linux/macOS are suitable for offline tests only.

python -m venv .venv
.venv\Scripts\python -m pip install .
Copy-Item config.example.toml config.local.toml

Edit config.local.toml with your existing identity file, an already verified known-hosts file, and your export directory. The module never auto-enrols a host key or prompts for a password. Confirm the device fingerprint through a trusted channel first; an unverified key scan is not sufficient. Unlock passphrase-protected keys in your SSH agent before starting the server. Run as your normal Windows user, with access to these files and the USB network; administrator rights are not required.

If USB is detected but has only an automatic 169.254.* address, reconnect the USB data cable while the tablet is awake and check whether DHCP recovers. This server never changes network configuration. If the route remains unsuitable, it stops.

MCP host configuration

Add an entry to your host's existing MCP server configuration, substituting your paths:

{
  "mcpServers": {
    "remarkable-usb": {
      "command": "C:/path/to/venv/Scripts/remarkable-usb-mcp.exe",
      "args": ["--config", "C:/path/to/config.local.toml"]
    }
  }
}

The server uses stdio and does not listen on an HTTP port. MCP protocol data is the only stdout output. Errors go to the protocol result or stderr. The local export tool is marked as writing a file, while device checks/listing are marked read-only.

Python integration

from remarkable_usb_mcp.config import Config
from remarkable_usb_mcp.device import UsbDevice

device = UsbDevice(Config.load("C:/path/to/config.local.toml"))
status = device.check_connection()
documents = device.list_documents()
# Select an explicit UUID from documents before calling device.export_rmdoc(uuid).

Export checks each member's SHA256 against manifests read before and after transfer. Limits apply to process duration, response bytes, archive members and expanded bytes. Unsafe paths, links, unexpected members and inconsistent snapshots are refused. A ZIP is closed and checked before atomic publication using a no-overwrite hard link; the export directory therefore needs a filesystem supporting hard links, such as NTFS. Failures remove only the operation's temporary file.

Development

.venv\Scripts\python -m pip install -e ".[dev]"
.venv\Scripts\python -m pytest
.venv\Scripts\ruff check .
.venv\Scripts\python -m build

Tests use generated metadata, generated archives and mocked USB sockets. They do not need a tablet, private key, account, real documents or machine-specific records.

This repository contains generic source, examples and synthetic tests only. Keep real configuration, host identities, keys, documents, logs, captures and acceptance records outside the repository. No document contents are sent to a cloud service by this module.

References

• Model Context Protocol: build a server

• Official MCP Python SDK

• Microsoft: IPv4 socket options and IP_UNICAST_IF

Independent project; not an official reMarkable product. MIT licensed.

中文说明

这是独立的只读 USB 连接模块，同时提供 Python 接口与标准 MCP 接口，供阅读器等应用复用。 当前支持 Windows10/11；直接识别可用 USB 地址，并在套接字层绑定 USB 网卡。 不要求 USB 成为系统默认路由，不检查或干预其他网络连接。 仅使用已核实的 USB 直连；连接条件不满足就停止，不改网络设置、不自动重试。

将示例配置中的三个路径改成自己的密钥、已核实主机身份文件和导出目录，再配置 MCP 客户端。 已有设备 SSH 权限是前提，服务器不自动添加主机信任，也不上传、删除或改写设备文档。 导出只新增本地文件，不覆盖已有文件，并核对全部成员的导出前后摘要。

本仓库不附带任何本机记录、真实文档、密钥、主机身份或联调日志。 笔画解析和批注 PDF 重建属于上层应用，不包含在本连接模块中。