appflowy-mcp 0.1.8

AppFlowy MCP server for workspace, space, page, database, and row operations

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

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

Environment Variables

Set these environment variables:

APPFLOWY_EMAIL=[e-mail]
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.