AppFlowy MCP

An MCP server for AppFlowy. This fork adds workspace folder, space, page, trash, favorite, and basic page-content tools on top of the original workspace/database/row tools.

Requirements

• Python 3.14
• uv
• AppFlowy account credentials

Configure In Codex

codex mcp add appflowy -- uvx appflowy-mcp --env APPFLOWY_EMAIL="your-email" --env APPFLOWY_PASSWORD="your-password" 

Option 1: PyPI / uvx

Use this after the package is published to PyPI. This is the simplest setup for daily use.

Use uvx as the command:

uvx

Use these arguments:

appflowy-mcp

Option 2: Local Source / uv

Use this when developing the MCP locally or running directly from a cloned repository.

Use uv as the command:

uv

Use these arguments:

run
--project
D:\codes\MCP\Appflowy-MCP
D:\codes\MCP\Appflowy-MCP\main.py

Configure In Claude-code

claude mcp add appflowy -- uvx appflowy -e APPFLOWY_EMAIL=your-email -e APPFLOWY_PASSWORD=your-password

Environment Variables

Set these environment variables:

APPFLOWY_EMAIL=your-email@example.com
APPFLOWY_PASSWORD=your-password

With these variables set, tools automatically log in on first use. appflowy_login is still available when you want to provide credentials explicitly.

For self-hosted AppFlowy, also set the base URL:

APPFLOWY_BASE_URL=http://localhost:8000

If omitted, APPFLOWY_BASE_URL defaults to https://beta.appflowy.cloud.

AppFlowy Structure

Most write operations need both a workspace and a parent view:

workspace -> space -> page/database

To create a page inside a space, pass the workspace ID and use the space view_id as parent_view_id.

Tools

Authentication

• appflowy_login
• appflowy_refresh_token

Workspaces And Spaces

• appflowy_list_workspaces
• appflowy_get_workspace_folder
• appflowy_list_spaces
• appflowy_create_space
• appflowy_update_space

Pages

• appflowy_create_page
• appflowy_get_page
• appflowy_update_page
• appflowy_move_page_to_trash
• appflowy_restore_page_from_trash
• appflowy_delete_page_from_trash
• appflowy_favorite_page
• appflowy_list_trash
• appflowy_list_favorites

Page Content

• appflowy_save_page
• appflowy_append_page_content
• appflowy_append_text_to_page
• appflowy_append_blocks_to_page
• appflowy_create_markdown_page
• appflowy_append_markdown_to_page
• appflowy_import_markdown_file
• appflowy_import_markdown_directory

Page-content support covers appending new document blocks, creating pages from Markdown, and appending Markdown to existing pages. AppFlowy exposes a high-level append-block endpoint, but not a matching high-level REST endpoint for deleting or editing arbitrary existing blocks. Page-level deletion through trash is supported.

When saving AI answers, notes, summaries, or generated content into AppFlowy, use appflowy_save_page by default. Its content_format field defaults to markdown, so agents do not need to ask users to say "save as Markdown" every time. Set content_format to plain_text only when the user explicitly wants the content preserved as literal plain text.

Use appflowy_append_page_content by default when adding AI-generated content to an existing page. It also treats content as Markdown unless content_format is set to plain_text.

Example paragraph block:

{
  "type": "paragraph",
  "data": {
    "delta": [
      {
        "insert": "Hello from MCP"
      }
    ]
  }
}

Example Markdown page:

{
  "parent_view_id": "space-or-page-view-id",
  "title": "Meeting Notes",
  "content": "# Meeting Notes\n\n- [ ] Follow up\n- **Important** decision\n\n```python\nprint(\"hello\")\n```",
  "content_format": "markdown"
}

Markdown conversion supports headings, paragraphs, dividers, bullet lists, numbered lists, todo lists, quotes, code blocks, image links, and inline bold, italic, strikethrough, code, and links.

Markdown Import

Use appflowy_import_markdown_file to import one local Markdown file as an AppFlowy page. Use appflowy_import_markdown_directory to recursively import a local folder tree.

Directory import maps local structure directly to AppFlowy:

local folder -> AppFlowy page
local subfolder -> AppFlowy subpage
local .md/.markdown file -> AppFlowy page

README.md or index.md becomes the content of its folder page instead of a separate child page. Other Markdown files in the same folder become child pages. Hidden folders plus .git, .hg, .svn, .idea, .vscode, node_modules, and __pycache__ are skipped.

Local image references are resolved relative to the Markdown file, uploaded to AppFlowy file storage, and replaced with AppFlowy file URLs:

![Architecture](./images/architecture.png)
![Screenshot](../assets/screenshot.png)

Remote image URLs such as https://... are kept as-is. Missing local images are reported in the import result warnings, while other files continue importing.

Example directory import:

{
  "parent_view_id": "space-or-page-view-id",
  "path": "D:\\notes",
  "upload_assets": true
}

Example single-file import:

{
  "parent_view_id": "space-or-page-view-id",
  "path": "D:\\notes\\MCP\\config.md",
  "title": "MCP Config",
  "upload_assets": true
}

Databases And Rows

• appflowy_list_databases
• appflowy_get_database_fields
• appflowy_list_rows
• appflowy_get_row_details
• appflowy_create_row
• appflowy_upsert_row
• appflowy_get_updated_rows

Local Run

uv run appflowy-mcp

Publish To PyPI

Build and check the package:

uv build
uv publish --dry-run --trusted-publishing never

Publish with a PyPI API token:

$env:UV_PUBLISH_TOKEN="pypi-your-token"
uv publish --trusted-publishing never

Do not commit PyPI tokens or write them into project files.

Notes

• Tokens are stored in memory by the MCP server process.
• APPFLOWY_EMAIL, APPFLOWY_PASSWORD, and APPFLOWY_BASE_URL can also be provided through a local .env file.
• Some page and space endpoints are implemented from AppFlowy source routes that are not present in the public OpenAPI document.