AppFlowy MCP Server

A Model Context Protocol server that gives AI assistants full read/write access to AppFlowy Cloud: workspaces, folders, pages, databases, trash, and favourites. It also converts Markdown into real AppFlowy document blocks, so an agent can write a properly formatted page instead of dumping a wall of plain text.

One file, three dependencies, no build step.

Why this exists: AppFlowy Cloud issues short-lived JWTs. Pasting a fresh token into your MCP config every hour is miserable, so this server logs in and refreshes tokens on its own and caches the session at ~/.appflowy_mcp_token.json. You configure credentials once and forget about auth.

---

Quick start

git clone https://github.com/ChaosChild/appflowy-mcp.git
cd appflowy-mcp
pip install -r requirements.txt
cp .env.example .env      # then fill in your credentials
python appflowy_mcp.py    # starts the stdio server; Ctrl+C to stop

The server speaks JSON-RPC over stdin/stdout, so running it directly just waits silently for a client. That silence means it started correctly. Wire it into a client below.

Claude Code

claude mcp add appflowy \
  --env APPFLOWY_BASE_URL=https://beta.appflowy.cloud \
  --env APPFLOWY_EMAIL=you@example.com \
  --env APPFLOWY_PASSWORD=your-password \
  -- python -u /absolute/path/to/appflowy_mcp.py

Claude Desktop

Config file: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).

{
  "mcpServers": {
    "appflowy": {
      "command": "python",
      "args": ["-u", "/absolute/path/to/appflowy_mcp.py"],
      "env": {
        "APPFLOWY_BASE_URL": "https://beta.appflowy.cloud",
        "APPFLOWY_EMAIL": "you@example.com",
        "APPFLOWY_PASSWORD": "your-password"
      }
    }
  }
}

<details> <summary><b>Other clients</b> (Antigravity, Hermes, OpenCode)</summary>

Antigravity (~/.gemini/config/mcp_config.json, or .agents/mcp_config.json per workspace) uses the same mcpServers shape as Claude Desktop above.

Hermes Agent (~/.hermes/config.yaml):

mcp_servers:
  appflowy:
    command: "python"
    args: ["-u", "/absolute/path/to/appflowy_mcp.py"]
    env:
      APPFLOWY_BASE_URL: "https://beta.appflowy.cloud"
      APPFLOWY_EMAIL: "you@example.com"
      APPFLOWY_PASSWORD: "your-password"

OpenCode (~/.config/opencode/opencode.jsonc). Note it uses environment, not env:

{
  "mcp": {
    "appflowy": {
      "type": "local",
      "command": ["python", "-u", "/absolute/path/to/appflowy_mcp.py"],
      "enabled": true,
      "environment": {
        "APPFLOWY_BASE_URL": "https://beta.appflowy.cloud",
        "APPFLOWY_EMAIL": "you@example.com",
        "APPFLOWY_PASSWORD": "your-password"
      }
    }
  }
}

</details>

Any MCP client that can launch a stdio process works. Use an absolute path to appflowy_mcp.py, and point command at the interpreter of the environment where you installed the requirements.

---

Authentication

Set APPFLOWY_BASE_URL plus one of the three options. Credentials can live in .env next to the script or in the client's env block; the client's environment wins.

Option	Variables	Trade-off
A. Email + password (recommended)	APPFLOWY_EMAIL, APPFLOWY_PASSWORD	Zero maintenance. Password sits in a config file.
B. Refresh token	APPFLOWY_REFRESH_TOKEN	Zero maintenance, no password on disk. Call get_auth_token once with a password grant to mint one.
C. Access token	APPFLOWY_ACCESS_TOKEN	No stored secret beyond a short-lived JWT, but you re-paste it roughly hourly.

On every call the server walks this chain and stops at the first thing that works: cached token, APPFLOWY_ACCESS_TOKEN, cached refresh token, APPFLOWY_REFRESH_TOKEN, then email/password login. A token expiring within 60 seconds counts as expired, and any 401 triggers one automatic re-auth and retry. Delete ~/.appflowy_mcp_token.json to force a clean login.

Self-hosted AppFlowy works: set APPFLOWY_BASE_URL to your instance. Every tool also takes optional base_url and access_token arguments to override per call.

---

Tools

Twenty-two tools. Every one returns the parsed JSON response, or {"error": ..., "details": ...} on failure, so an agent can read the error rather than crash on it.

Auth

Tool	Purpose
get_auth_token	Mint an access + refresh token pair via password or refresh grant.

Workspaces and folders

Tool	Purpose
get_workspace_list	List all workspaces for the authenticated user.
get_workspace_folder	Walk the page/folder tree. Takes depth and root_view_id.

Databases

Tool	Purpose
get_databases	List databases in a workspace.
get_database_fields	Field (column) definitions, including field IDs.
get_database_row_ids	All row UUIDs in a database.
get_database_rows_detail	Cell values for specific rows, optionally with row documents.
get_updated_database_row_ids	Rows changed after an ISO 8601 timestamp.
create_database_row	Add a row from a cells map, plus optional Markdown body.
upsert_database_row	Update or insert a row, keyed by pre_hash.

Pages

Tool	Purpose
create_page	Create a document, grid, board, or calendar page.
get_page	Fetch a page's metadata and content.
update_page	Rename, set an icon, lock or unlock. Only sends fields you pass.
move_page_to_trash	Soft delete.

Markdown documents

Tool	Purpose
create_document_from_markdown	New page from Markdown, converted to real blocks.
append_markdown_to_page	Append blocks to an existing page, keeping its view_id.
replace_page_document	Replace a page body. See the caveat below.

Trash and favourites

Tool	Purpose
get_trash	List trashed pages.
restore_page_from_trash	Restore a trashed page.
delete_page_permanently	Irreversible delete.
get_favorite_pages	List favourites.
toggle_favorite_page	Add or remove a favourite.

---

Markdown conversion

create_document_from_markdown and append_markdown_to_page run Markdown through a small parser that emits AppFlowy's block tree, so headings are real headings and checkboxes are real checkboxes.

Markdown	AppFlowy block
# ... through ###### ...	heading (levels 1 to 6)
Paragraph text (wrapped lines join)	paragraph
- item, * item, + item	bulleted_list
1. item	numbered_list
- [ ] item, - [x] item	todo_list with checked
> quote (consecutive lines merge)	quote
---, ***, ___	divider
```lang fenced block	code with language
**bold**, *italic*, `code`, [text](url)	inline delta attributes
Pipe tables	code block, formatting preserved

Known limits, by design:

• Tables render as a code block. AppFlowy's table blocks are a nested structure this parser does not generate; a monospaced table still reads fine.
• Nested lists flatten to one level. Indentation is not tracked.
• Images are supported through create_page's raw page_data, not through Markdown ![]() syntax.
• If your AppFlowy build rejects code or quote blocks with InvalidBlock, set FALLBACK_CODE_AS_PARAGRAPH or FALLBACK_QUOTE_AS_PARAGRAPH to True near the top of the conversion section to degrade them to paragraphs.

The replace_page_document caveat

AppFlowy Cloud has no in-place "set body" endpoint. The only true whole-document replace is the CRDT full-sync route, which needs Yjs encoding in Python and is out of scope here. So replace_page_document recreates the page: it reads the original's parent, name, and icon, creates a new page under the same parent, then trashes the original.

Consequences you should know about before calling it:

• The page gets a new view_id. Existing links to it break.
• It lands at the end of its parent section, so ordering may need a manual fix.
• Page history does not carry over.
• If creation fails, the original is left untouched.

Prefer append_markdown_to_page when you only need to add content. It uses /append-block, keeps the view_id, and preserves history.

---

Using it with an AI agent

skills/appflowy/SKILL.md is a ready-made agent skill covering the workflows that are easy to get wrong: resolving IDs before acting, choosing between append and replace, writing database cells, and handling trash safely.

For Claude Code, install it with:

mkdir -p ~/.claude/skills
cp -r skills/appflowy ~/.claude/skills/

For other agents, the file is plain Markdown. Paste it into your system prompt, AGENTS.md, or the equivalent.

---

Development

pip install -r requirements.txt pytest
python -m pytest

The suite is fully offline: no network, no AppFlowy account, and it redirects the token cache to a temp file so your real session is never touched. It covers JWT validation and the auth fallback chain, HTTP error and retry handling, the Markdown parser, and each tool's request shaping.

CI runs the same suite on Python 3.10 through 3.13.

Pull requests are welcome. See CONTRIBUTING.md.

---

Security notes

• Never commit .env. It is gitignored, along with anything matching .env.* except the example.
• ~/.appflowy_mcp_token.json holds a live access and refresh token in plaintext, with whatever permissions your umask gives it. Treat it as a credential.
• MCP servers run with your full account access. This one can permanently delete pages via delete_page_permanently. Review what your agent proposes before approving destructive calls.
• Option B or C avoids storing a reusable password in a config file that agents and backup tools can read.

License

MIT. See LICENSE.