zenread
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
.mdfiles 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 |
| bionic reading (the first letters of each word in bold) |
| focus (off, paragraph, line) and how strongly the rest is dimmed |
| play the note word by word; Space pauses, ↑ ↓ step, |
| previous, next heading |
| select a link, follow it (wiki links |
| back to the note you came from |
| next, previous note in the folder |
| 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 servershells/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 zenreador 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 |
| shows a note in the reader |
| the note's text, properties, web link, the notes before and after it, and where its links point |
| the folders and notes in a folder |
| 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 archiveThe 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
Set the same version in
package.jsonandplugin.json, and commit.npm run packbuilds everything and writesdist/zenread-<version>.tgz(the manifest, the one-file server, the built UI, skills, README, LICENSE: no links, dot files ornode_modules) and prints its sha256.npm run test:packunpacks it into an empty folder and runs the MCP smoke test against that server.Tag
v<version>and push the tag. The release workflow checks that the tag,package.jsonandplugin.jsonagree, runs the checks, and publishes a GitHub release with the archive and its sha256.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 testTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search, read, write, and organize your Scratchpad notes from any MCP client.
AgentDocs (agentdocs.eu) MCP: read, search, write, comment, share & attach images to Markdown docs.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.415 npm1MIT
- AlicenseAqualityBmaintenanceEnables AI clients to read Markdown notes from a single explicitly granted local folder, read-only, with strict containment against access outside that folder.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to search, read, and list notes and tags in a Markdown vault using read-only tools.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible clients to create, list, search, and delete notes, read all notes as markdown, and use prompts to summarize or clean up notes.MIT