Appflowy MCP

🐳m2n2/appflowy-mcp:lateston Docker Hub

Aself-hosted, token-scopedModel Context Protocolserver forAppFlowy. It gives AI agents (Claude, or any MCP client) tools to read and edit your AppFlowy workspaces — list workspaces, walk the page tree, create/update/read pages, and edit individual blocks in place — whilebounding each client to exactly the pages you allowvia per-token tree-shaped scopes.

- 🔒Token-scoped access.The server logs into AppFlowy once as a service account. Clients never see those credentials — they present an opaque token, and each token is restricted to a set of workspaces / page subtrees.
- 🌳Tree-shaped scopes.Grant a whole workspace, a top-level page and everything under it, or a page four levels deep and its descendants. Mix and match several grants per token.
- 🐳Runs anywhere.Streamable-HTTP transport, small multi-arch image (m2n2/appflowy-mcp, amd64 + arm64) on Docker Hub, ready for Docker Compose, Kubernetes, or a Helm chart.
- ✏️Real editing.Append blocks, insert blocks at any position, edit block text (rich formatting preserved), and delete blocks — via the same Yjs/CRDT path the official web client uses.

┌─────────────┐ token: scopes ┌──────────────┐ MCP client │ Authorization: Bearer <token> ──────────▶ │ appflowy-mcp │ (Claude) └─────────────┘ │ enforces │ │ scope, then │ │ acts as the │ service account (email+password / JWT) ◀──────│ service acct │ └──────┬───────┘ ▼ AppFlowy Cloud REST

APPFLOWY_MCP_TOKENS='[ {"token":"sk-full", "name":"full", "scopes":[]}, {"token":"sk-teamws", "name":"team", "scopes":["WORKSPACE_ID"]}, {"token":"sk-project", "name":"project", "scopes":["WORKSPACE_ID/ROOT_VIEW_ID", "WORKSPACE_ID/A/B/DEEP_VIEW_ID"]} ]'

APPFLOWY_MCP_TOKEN_0=sk-full APPFLOWY_MCP_TOKEN_0_NAME=full APPFLOWY_MCP_TOKEN_0_SCOPES= # empty => all workspaces APPFLOWY_MCP_TOKEN_1=sk-project APPFLOWY_MCP_TOKEN_1_NAME=project APPFLOWY_MCP_TOKEN_1_SCOPES=WORKSPACE_ID/ROOT_VIEW_ID,WORKSPACE_ID/A/B/DEEP_VIEW_ID

appflowy: base_url: https://appflowy.example.com email: service@example.com password: ${APPFLOWY_PASSWORD} # plain string; env is not interpolated — set real value server: host: 0.0.0.0 port: 8000 path: /mcp require_auth: true tokens: - token: sk-full name: full scopes: [] # all workspaces - token: sk-project name: project scopes: - WORKSPACE_ID/ROOT_VIEW_ID # a page + its whole subtree - WORKSPACE_ID/A/B/DEEP_VIEW_ID # a deep page + its subtree

Seeconfig.example.yamland.env.example.

docker run --rm -p 8000:8000 \ -e APPFLOWY_BASE_URL=https://appflowy.example.com \ -e APPFLOWY_EMAIL=service@example.com \ -e APPFLOWY_PASSWORD=secret \ -e APPFLOWY_MCP_TOKENS='[{"token":"sk-full","scopes":[]}]' \ m2n2/appflowy-mcp:latest

cp .env.example .env # fill in values docker compose up -d

helm install appflowy-mcp ./deploy/helm \ --set appflowy.baseUrl=https://appflowy.example.com \ --set appflowy.email=service@example.com \ --set appflowy.password=secret \ --set-json 'tokens=[{"token":"sk-full","scopes":[]}]'

The server speaksstreamable HTTPathttp://HOST:PORT/mcp. Point your MCP client at it and send the token as a bearer header. For Claude Code:

{ "mcpServers": { "appflowy": { "type": "http", "url": "https://appflowy-mcp.example.com/mcp", "headers": { "Authorization": "Bearer sk-full" } } } }

Health check:GET /healthz→{"status":"ok"}.

- Block-editing tools requirepycrdt(bundled). They mirror the web client's CRDTweb-update; there is no official per-block REST endpoint.
- Insert blockwithblock_type="image"embeds a public image URL by reference (nothing is uploaded); remove it withDelete blocklike any block.
- Database row cells are keyed by fieldname or id; values follow the field type (string for text/URL, number for Number, bool for Checkbox, ISO-8601 or unix seconds for DateTime, option name(s) for select).Create database rowgoes through the REST endpoint;Update database rowandDelete database rowact on an existing row by its id through the CRDTweb-updatepath (mirroring the web client), since REST exposes no route to edit or delete a row by UUID.
- Scope checks rely on the workspace folder tree, cached forAPPFLOWY_MCP_FOLDER_CACHE_TTLseconds. Newly created pages invalidate the cache for their workspace.
- Open mode (APPFLOWY_MCP_REQUIRE_AUTH=falsewith no tokens) grants full access to anyone who can reach the port — only use on a trusted network.

uv sync # install runtime + dev dependencies uv run pytest # run the test suite with the 100% coverage gate uv run ruff check # lint

The suite enforces100% line and branch coverage(--cov-fail-under=100inpyproject.toml). CI runs it as thetestjob in.github/workflows/docker.yml; the Docker image buildneeds: test, so a failing test or a coverage drop blocks the image from ever being built. SeeAGENTS.mdfor the testing definition of done.

This project began as a self-hosting-focused rework ofLucasXu0/appflowy_mcp.

Interact with Apple Notes using natural language on macOS.