Skip to main content
Glama
zenread
by Zegoverno

zenread

A calm reader for Markdown notes, with reading aids. One code base, three ways to run it:

  • a PWA: static files, installable on desktop and Android, works offline, nothing uploaded;

  • a zenbot plugin: "Read" for .md files in Files, and a /read <path> command;

  • an MCP App: the reader as an inline widget in Claude, ChatGPT and any host that supports MCP Apps, with tools the agent can call.

MIT licensed. No account, no telemetry, no network calls. It reads Markdown only and never writes to your files.

Read

Open a folder (or some .md files) from the start page, or try the aids on the built-in sample. The page shows the note's properties (front matter), its text, and the minutes left to read. Keyboard:

Key

Does

↑ ↓, PgUp PgDn, Space, Home, End

scroll

< >

narrower, wider text column (60, 72, 90 characters, full width)

:

spaced lines and letters

b

bionic reading (the first letters of each word in bold)

f, d

focus (off, paragraph, line) and how strongly the rest is dimmed

p

play the note word by word; Space pauses, ↑ ↓ step, + - speed, . pauses at punctuation

[ ]

previous, next heading

l L, Enter

select a link, follow it (wiki links [[Note]], relative .md links, web links)

←, Backspace

back to the note you came from

n N

next, previous note in the folder

i, h

the note's properties; the history of notes read

Alt+O

open another folder

The settings (width, spacing, bionic, focus, dim) are remembered: in the browser's local storage in the PWA, in the plugin's data folder when run as a plugin.

Related MCP server: wyrd-mcp

Run it standalone (PWA)

npm ci
npm run build          # the PWA is in shells/web/dist: serve that folder with any static server
npm run dev            # development server

shells/web/dist is plain static files (relative URLs), so GitHub Pages, Cloudflare Pages or any file server hosts it. Open it in a browser and use Install (desktop Chrome/Edge, Android) to keep it as an app; after the first visit it works offline. Folders open with the File System Access API where the browser has it, and an <input type=file> fallback everywhere else. Your notes stay in the browser: nothing is sent anywhere.

Install it in zenbot

zen plugins add zenread

or open Settings → Marketplace in zenbot's web app and install it there. To try a build first: zen plugins add ./zenread-0.1.1.tgz. zenbot shows the permission below and asks you to approve it.

It lives in Files, not a separate Reading tab. It adds an opener for *.md files in read mode (set it as the default in Settings → Plugins; until then the built-in reader stays the default), and the /read <path> command. zenbot passes the file's path in its host context (zen.path, zen.pane, zen.slot); a link to another note is handed back to zenbot with zen://open?path=…, which opens it with the right opener. Changes to a note on disk show up in the reader within a couple of seconds.

Permission: files:read. The server reads notes under the folder zenbot gives it (ZEN_PLUGIN_FILES) and keeps the reading settings in its own data folder (ZEN_PLUGIN_DATA). It has no network and cannot write your files.

Use it in Claude, ChatGPT or another MCP Apps host

Download zenread-<version>.tgz from the releases and unpack it (it needs only Node 22 or newer, no npm install), or build it yourself (see Develop). Then add a stdio server whose command is node and whose argument is the absolute path of mcp/dist/server.js, with the environment variable ZEN_PLUGIN_FILES set to the absolute path of your notes folder (and, if you like, ZEN_PLUGIN_DATA to a folder for the settings). Without ZEN_PLUGIN_FILES the file tools say so and refuse; the reader still opens. In a host there is no zenbot, so links to other notes open inside the reader.

Tool

Does

zenread_open

shows a note in the reader

zenread_read

the note's text, properties, web link, the notes before and after it, and where its links point

zenread_list

the folders and notes in a folder

zenread_settings

app only: loads and saves the reading aids' settings

Every path is relative to the notes folder. .., absolute paths, symlinks that leave the folder, dot files and dot folders, and anything that is not .md are refused. The view is ui://zenread/app. Hosts that only speak remote (HTTP) MCP need a bridge: the server speaks stdio only.

Roadmap

  • PDF and EPUB

  • web pages saved as readable text

  • highlights and notes in the margin (the first write permission)

  • AI help (summarize, ask) through MCP sampling in hosts and through ACP in the desktop app

  • desktop (Tauri) and mobile (Capacitor) shells

Develop

npm ci
npm run build    # the PWA, the app (ui/dist/index.html) and the server (mcp/dist/server.js)
npm run check    # types, unit tests, build, MCP smoke test, browser test, release archive

The browser test needs Playwright's Chromium (npx playwright install chromium). It loads the built PWA with a neutral fixture note, changes the width, follows a link and goes back, and runs the MCP App page against a fake host (with and without zenbot's host context). SHOTS=<folder> npm run test:e2e also writes screenshots there; keep them out of the repository.

Releasing

  1. Set the same version in package.json and plugin.json, and commit.

  2. npm run pack builds everything and writes dist/zenread-<version>.tgz (the manifest, the one-file server, the built UI, skills, README, LICENSE: no links, dot files or node_modules) and prints its sha256. npm run test:pack unpacks it into an empty folder and runs the MCP smoke test against that server.

  3. Tag v<version> and push the tag. The release workflow checks that the tag, package.json and plugin.json agree, runs the checks, and publishes a GitHub release with the archive and its sha256.

  4. List or upgrade the plugin in the zenbot marketplace with that archive URL and sha256 (see zenbot's PLUGINS.md).

Layout

plugin.json  the zenbot manifest: openers, commands, permissions
core/        settings, text and link rules: pure TypeScript, tested with vitest
ui/          the Svelte 5 app; host.ts is the MCP App entry, adapters.ts the storage seam
mcp/         the MCP server and its confined file access (built to mcp/dist/server.js)
shells/web/  the PWA: manifest, icons, service worker, entry
skills/      reading-notes: how an agent should use the tools
scripts/     pack.mjs: the release archive
tests/       MCP smoke test, browser test, release-archive test

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP clients to search and read notes from an Obsidian or markdown vault through four governed tools, with enforced read-only access, a page budget, and path sandboxing.
      4
      15 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI clients to read Markdown notes from a single explicitly granted local folder, read-only, with strict containment against access outside that folder.
      1
      MIT