quill-flowy

A lean, MIT-licensed Model Context Protocol (MCP) server that lets an AI agent (Claude Code, Claude Desktop, …) read — and, in a separate module, write — a self-hosted AppFlowy instance.

AppFlowy stores a page's body as a Yjs CRDT, not plain text, so the pages are a silo your agent can't see. quill-flowy authenticates to your instance, walks the workspace/page tree, and decodes the CRDT document into Markdown — the same thing AppFlowy's own web client does, using the same yjs library.

Companion to anythingllm-mcp — same minimal Node + @modelcontextprotocol/sdk stack, same safety posture.

Tools

Read (Phase 1 — always on, strictly read-only):

Write (Phase 2 — mutating, opt-in): create_page, append_to_page, rename_page, move_page. These live in a separate module and are registered only when QUILL_FLOWY_WRITE=1, so the default install exposes zero write surface to the agent. All four are additive or reversible (none deletes content). append_to_page converts Markdown to AppFlowy blocks (headings, lists, to-dos, code, quotes, formatting).

update_page (replace an existing body in place) is not supported: AppFlowy exposes no high-level endpoint for editing/deleting arbitrary existing blocks — it would require raw Yjs collab over the sync protocol. Use append_to_page to add content, or edit in the AppFlowy app.

Related MCP server: appflowy-mcp

Requirements

• Node 18+ (developed on Node 24).

• A self-hosted AppFlowy Cloud instance with a password-based account.

Install

git clone https://github.com/DezGDNY/quill-flowy
cd quill-flowy
npm install

Register it with your MCP client, passing config via an env block, e.g. Claude Code:

claude mcp add quill-flowy --scope user -- node /absolute/path/to/quill-flowy/index.js

with APPFLOWY_BASE_URL, APPFLOWY_EMAIL, and APPFLOWY_PASSWORD set in the environment (see .env.example).

Configuration

Secure credential handling

Don't store a plaintext password in production. On Windows, keep it in a DPAPI-encrypted file and use a small launcher that decrypts it into APPFLOWY_PASSWORD in-process before exec'ing the server — the password never touches disk in plaintext, your shell history, or your MCP config. (On macOS/Linux, use the OS keychain or a secret manager the same way.) quill-flowy itself only ever reads APPFLOWY_PASSWORD from its environment and uses it for a single login; it is never logged.

How it works

1. Auth: POST /gotrue/token?grant_type=password → JWT bearer (cached; re-login on expiry).

2. Navigate: GET /api/workspace… and …/folder?depth=N give the workspace and page tree directly — no decoding needed.

3. Read a body: GET /api/workspace/v1/{wid}/collab/{vid}?collab_type=0 returns the Yjs doc_state; quill-flowy loads it with yjs and walks the AppFlowy document schema (data → document → blocks / meta.children_map / meta.text_map) into Markdown, reading each text run's delta for inline formatting.

License

MIT © 2026 Dez