AppFlowy MCP Server

AppFlowy MCP Server

An open-source AppFlowy MCP server (Model Context Protocol) for connecting Claude, Cursor, Codex and other MCP clients to your AppFlowy workspace. Give AI agents tools to edit Markdown documents, update typed database rows and Board cards, search pages, and import or export Markdown trees.

Run locally with uvx or Docker, or serve authenticated Streamable HTTP. The compact profile exposes 11 async workflow tools with typed inputs, bounded responses and explicit results for partial batch failures.

Independent community project; not affiliated with or endorsed by AppFlowy. The tested self-hosted baseline is Cloud 0.21.4 with Web 0.20.12. See compatibility and limitations before choosing a deployment.

Quick start · Client setup · Tools · Choosing a server · Compatibility

Quick start

Requires Python 3.11+ and uv, or Docker. The commands below use the published 2.2.0 release. main can contain unreleased fixes; see CHANGELOG.md.

Create a private .env file with a dedicated AppFlowy bot account:

APPFLOWY_EMAIL=bot@example.com

APPFLOWY_PASSWORD=replace-with-the-bot-password ALLOWED_WORKSPACE_IDS=replace-with-workspace-id

APPFLOWY_BASE_URL=https://your-self-hosted-appflowy.example.com

An APPFLOWY_ACCESS_TOKEN can replace email/password. It takes precedence and must be replaced when it expires. .env.example lists all settings.

Local MCP client (stdio)

Run without cloning or creating a virtual environment:

uvx --from git+https://github.com/Rahulk644/Appflowy-MCP-Server@v2.2.0 \

appflowy-mcp --env-file /absolute/path/to/.env

Example Claude Desktop/Cursor-style configuration:

{

"mcpServers": { "appflowy": { "command": "uvx", "args": [ "--from", "git+https://github.com/Rahulk644/Appflowy-MCP-Server@v2.2.0", "appflowy-mcp", "--env-file", "/absolute/path/to/.env" ] } } }

Client recipes also cover Claude Code, Codex and Docker. Check configuration and workspace access with the same launcher:

uvx --from git+https://github.com/Rahulk644/Appflowy-MCP-Server@v2.2.0 \

appflowy-mcp doctor --check --env-file /absolute/path/to/.env

doctor without --check stays offline; --json produces a sanitized report.

Docker

The public image supports Linux amd64 and arm64. For stdio:

docker run --rm -i --env-file .env \

ghcr.io/rahulk644/appflowy-mcp-server:2.2.0 appflowy-mcp

For HTTP, add MCP_SECRET_TOKEN to .env and run:

docker run --rm --env-file .env -p 127.0.0.1:8000:8000 \

ghcr.io/rahulk644/appflowy-mcp-server:2.2.0

The MCP endpoint is /mcp/; legacy SSE is /sse/. The image is listed in the official MCP Registry. PyPI publication is deferred. RELEASING.md covers publishing.

For a source-built service, configure .env and run docker compose up -d --build. The Compose file does not publish a port; connect it to your HTTPS reverse proxy. Traefik labels require an existing proxy and shared Docker network. The optional deploy_vps.sh starts the service; it does not provision public routing or TLS.

Built for AppFlowy workflows

• Typed database edits: resolve field names and select options, write Number, Checkbox and DateTime/range cells, and update existing Board cards in batches.
• Markdown documents: create and edit pages or row bodies, use guarded replacement, native simple tables, and import/export document trees with continuation cursors. Upload small files and optionally insert image blocks.
• A compact interface: group related operations into async workflows, with an exclusive legacy profile for existing integrations and a read-only profile for discovery.
• Deployment choice: published amd64/arm64 Docker images, a Git-based uvx command, local stdio and authenticated HTTP. No source checkout is required.
• Tested self-hosted baseline: disposable AppFlowy integration checks and browser assertions for typed Grid cells, Board grouping, Formula and Timeline rendering. Exact versions and validation limits are in COMPATIBILITY.md.

Tools

The compact profile exposes 11 async tools, or 12 with experimental AI enabled. Parameters are typed JSON inside request. Commands reject non-default inputs they cannot apply. For example, update_cells does not accept row document text, and database creation does not accept Markdown. Use the relevant document command instead; the validation error names unused fields.

{"request":{"workspace_id":"WORKSPACE_ID","database_id":"DATABASE_ID","command":"update_cells","rows":[{"row_id":"ROW_ID","cells":{"Name":"Updated task","Done":true}}]}}

Follow returned next_offset values rather than adding the requested limit: a response may contain fewer complete items to fit its budget. Markdown reads use character offsets and a content hash; folder reads can target an id. Tree export returns complete files, a tree cursor, and fetch instructions for oversized documents. See the continuation contract.

APPFLOWY_TOOL_PROFILE=legacy exposes 36 tools: the original 34 names plus two comment tools. APPFLOWY_READ_ONLY=true exposes five read-only tools in compact mode and rejects API mutations. Profiles are exclusive. Read the migration table and agent guide, also available as appflowy://guide. Manifest measurements measure bytes, not LLM accuracy.

Configuration and HTTP access

For an installed command, appflowy-mcp --transport streamable-http listens on 127.0.0.1:8000; --host and --port change the bind address. Source checkouts also support python server.py and uvicorn server:app.

For Google OAuth, register a Google Web client with redirect URI https://YOUR_HOST/auth/google/callback, configure the OAuth settings above, and connect the MCP client to https://YOUR_HOST/mcp/. For shared-secret clients:

{"mcpServers":{"appflowy":{"url":"https://mcp.example.com/mcp/","headers":{"Authorization":"Bearer YOUR_MCP_SECRET_TOKEN"}}}}

The ?token=... URL form is supported for clients without header support; URLs can leak through proxies, logs and browser history. Prefer headers or OAuth.

All HTTP users act through the same AppFlowy account and server-wide workspace policy. OAuth identifies clients; it does not grant each client a separate AppFlowy role or page-subtree scope. Protect remote HTTP with authentication and HTTPS. See SECURITY.md.

Frequently asked questions

What is an AppFlowy MCP server?

An AppFlowy MCP server translates requests from an MCP client into AppFlowy operations. This community server uses AppFlowy's REST and collaboration APIs to read and edit documents, database schemas, rows and blocks. It is MIT licensed and is not an official AppFlowy product.

Can I connect Claude, Cursor or Codex?

Yes, through their MCP configuration. Use local stdio for a client-launched process or Streamable HTTP for a running service. Copy the client-specific recipes. Automated checks cover the MCP protocol and packaged server; individual desktop interfaces are not certified.

This server or AppFlowy's official MCP?

AppFlowy also provides its own MCP service and AI app plugins. Choose based on the deployment and access model your workflow needs:

| Self-hosted requirements | An AppFlowy account with the needed API permissions; no separate MCP license key | The official self-hosted MCP