rustpad-mcp

rustpad-mcp

A Model Context Protocol (MCP) server for Rustpad, the efficient, minimal, self-hosted collaborative text editor.

Lets MCP clients like Claude Code, Claude Desktop or Codex read and write the pads of a Rustpad instance: fetch a document, create one, replace it wholesale or edit it in place.

Eight tools is the ceiling, not the floor: RUSTPAD_ALLOW_TOOLS=essential registers a curated five instead, and a model picks the right tool far more reliably from five than from eight — see choosing which tools load.

Reads go through Rustpad's HTTP API; writes speak the operational-transformation WebSocket protocol, so targeted edits (append_to_document, replace_in_document) merge cleanly with what human collaborators type at the same time instead of overwriting it. While the server edits a pad, it is visible to everyone in the pad as a collaborator named rustpad-mcp.

Requirements

• A reachable Rustpad instance (self-hosted; the server is stateless and needs no credentials — Rustpad has no authentication)
• Node.js >= 22, or Docker

Configuration

Variable	Required	Description
RUSTPAD_URL	yes	Base URL of the instance, e.g. https://rustpad.example.net
RUSTPAD_READ_ONLY	no	true registers only the read tools
RUSTPAD_INSECURE_TLS	no	true accepts self-signed certificates (scoped to this connection only)
RUSTPAD_ALLOW_TOOLS	no	Comma-separated tool names, list_* prefixes, or essential for a curated preset
RUSTPAD_DENY_TOOLS	no	Same syntax; removed from whatever RUSTPAD_ALLOW_TOOLS left

The same URL serves the HTTP API, the WebSocket endpoint and the share links returned by the tools (<RUSTPAD_URL>/#<pad-id>). Booleans must be exactly true. The server starts and lists its tools without configuration; every call then fails with setup instructions.

Keep in mind what Rustpad is: pads are ephemeral (lost on server restart and after 24 hours of inactivity, unless the instance is run with SQLITE_URI) and anyone who knows a pad id can read and write it. Do not put secrets in pads.

Choosing which tools load

RUSTPAD_ALLOW_TOOLS and RUSTPAD_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of five: get_document, get_document_info, create_document, set_document, append_to_document.

RUSTPAD_ALLOW_TOOLS=essential
RUSTPAD_ALLOW_TOOLS=get_document,append_to_document
RUSTPAD_DENY_TOOLS=set_document

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under RUSTPAD_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add rustpad --env RUSTPAD_URL=https://rustpad.example.net -- npx rustpad-mcp

Claude Desktop

{
  "mcpServers": {
    "rustpad": {
      "command": "npx",
      "args": ["rustpad-mcp"],
      "env": {
        "RUSTPAD_URL": "https://rustpad.example.net"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.rustpad]
command = "npx"
args = ["-y", "rustpad-mcp"]

[mcp_servers.rustpad.env]
RUSTPAD_URL = "https://rustpad.example.net"

Docker

docker run -i --rm -e RUSTPAD_URL=https://rustpad.example.net ghcr.io/ni-c/rustpad-mcp

Tools

Tool	Description
get_document	Read the plain-text content of a pad
get_document_info	Content length, revision, language and the users editing right now
get_stats	Server statistics (uptime, number of documents)
create_document	Create a pad (random or chosen id), optionally with content and language
set_document	Replace the entire content — non-empty pads require a confirmation token
append_to_document	Append text; concurrent edits elsewhere survive
replace_in_document	Exact search & replace via OT; unique match required unless replace_all
set_language	Set the Monaco syntax-highlighting language

With RUSTPAD_READ_ONLY=true only the first three are registered.

Safety

• Pad content is world-writable and therefore untrusted: every read result is prefixed with a marker telling the model to treat it as data, never as instructions.
• Replacing a non-empty pad is irreversible and guarded by a single-use confirmation token that only ever appears in a previous tool result.
• Tool results are size-capped; upstream error bodies are sanitized before they reach the model.
• RUSTPAD_INSECURE_TLS relaxes certificate validation only for the configured connection, never process-wide.

Development

npm install
npm run lint && npm run build && npm test

The test suite talks to an in-memory fake of rustpad-server (including OT transformation of concurrent edits) over the real MCP protocol; no live instance is needed. The architecture diagram and social card are generated — edit docs/assets/architecture.source.svg and run npm run assets, never the rendered copies.

Releasing

Releases are tag-driven. Bump package.json, move the [Unreleased] notes in CHANGELOG.md under the new version, commit, then:

git tag -s vX.Y.Z -m "vX.Y.Z"
git push origin main vX.Y.Z

The release workflow publishes to npm via Trusted Publishing (OIDC, with provenance), pushes the multi-arch container image to GHCR, creates the GitHub release from the CHANGELOG section, and updates the entry in the official MCP registry.

License

MIT © Willi Thiel