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"
      }
    }
  }
}

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"
      }
    }
  }
}

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.

Related MCP server: AppFlowy MCP Server

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.

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

Workspaces and folders

Databases

Pages

Markdown documents

Trash and favourites

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.

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.