🚀 AppFlowy MCP Server

Connect your IDE to your self-hosted AppFlowy workspace

Installation • Configuration • Tools • File Attachments

✨ Features

• 🔍 Full-text search across all workspace content
• 📄 Document management — read, create, delete pages
• 📊 Database operations — CRUD on Grid, Board, Calendar, Gallery
• 📎 File attachments — upload, download, attach files to documents
• 🌐 Works with any MCP-compatible IDE — VS Code, Cursor, Claude Desktop, Zed, and more
• 🔐 Secure JWT authentication via GoTrue (Supabase Auth fork)
• 🏠 Self-hosted first — designed for AppFlowy Cloud self-hosted instances

📦 Installation

Option 1: Install via npx (recommended)

npx @mtcsistemas/appflowy-mcp-server

Option 2: Install globally

npm install -g @mtcsistemas/appflowy-mcp-server

Option 3: Clone and build from source

git clone https://github.com/AppFlowy-IO/appflowy-mcp-server.git
cd appflowy-mcp-server
npm install
npm run build

⚙️ Configuration

Create a .env file or set environment variables:

# Required: Your AppFlowy Cloud URL
APPFLOWY_BASE_URL=https://tu-appflowy.dominio.com

### Authentication Options

Choose **one** of the following authentication methods:

#### Option 1: Email and Password (Recommended)
```env
APPFLOWY_BASE_URL=https://appflowy.yourdomain.com
[email protected]
APPFLOWY_PASSWORD=your_password

Option 2: JWT Token

APPFLOWY_BASE_URL=https://appflowy.yourdomain.com
APPFLOWY_JWT_TOKEN=your_jwt_token_here

Optional: File upload limits

APPFLOWY_MAX_FILE_SIZE_MB=50 APPFLOWY_FILE_TIMEOUT_SEC=60

### Getting your JWT Token

1. Log in to your AppFlowy web app
2. Open browser DevTools → Application → Local Storage
3. Find the `gotrue` token or call:
   ```bash
   curl -X POST https://tu-appflowy.dominio.com/gotrue/token?grant_type=password \
     -H "Content-Type: application/json" \
     -d '{"email":"[email protected]","password":"your-password"}'

🖥️ IDE Setup

VS Code

Add to your settings.json:

{
  "mcp.servers": {
    "appflowy": {
      "command": "npx",
      "args": ["-y", "@appflowy/mcp-server"],
      "env": {
        "APPFLOWY_BASE_URL": "https://tu-appflowy.dominio.com",
        "APPFLOWY_EMAIL": "[email protected]",
        "APPFLOWY_PASSWORD": "tu-password-seguro"
      }
    }
  }
}

Cursor

In Settings → MCP Servers, add:

{
  "mcpServers": [
    {
      "name": "appflowy",
      "command": "npx -y @appflowy/mcp-server",
      "env": {
        "APPFLOWY_BASE_URL": "https://tu-appflowy.dominio.com",
        "APPFLOWY_EMAIL": "[email protected]",
        "APPFLOWY_PASSWORD": "tu-password-seguro"
      }
    }
  ]
}

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "appflowy": {
      "command": "npx",
      "args": ["-y", "@appflowy/mcp-server"],
      "env": {
        "APPFLOWY_BASE_URL": "https://tu-appflowy.dominio.com",
        "APPFLOWY_JWT_TOKEN": "eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}

Zed

Add to your settings.json:

{
  "assistant": {
    "version": "2",
    "default_model": {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-latest"
    },
    "enable_experimental_live_diffs": true
  },
  "context_servers": {
    "appflowy-mcp-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@appflowy/mcp-server"],
        "env": {
          "APPFLOWY_BASE_URL": "https://tu-appflowy.dominio.com",
          "APPFLOWY_EMAIL": "[email protected]",
          "APPFLOWY_PASSWORD": "tu-password-seguro"
        }
      }
    }
  }
}

🛠️ Available Tools

Workspace Tools

| Tool | Description | |------|-------------| | appflowy_list_workspaces | List all available workspaces | | appflowy_get_workspace | Get details of a specific workspace |

Document Tools

| Tool | Description | |------|-------------| | appflowy_list_documents | List documents in a workspace/folder | | appflowy_read_document | Read full content of a document | | appflowy_create_document | Create a new document/page | | appflowy_delete_document | Delete a document | | appflowy_duplicate_document | Duplicate/clone a document |

Database Tools

| Tool | Description | |------|-------------| | appflowy_list_databases | List all databases (Grid, Board, Calendar, Gallery) | | appflowy_read_database | Read all rows from a database | | appflowy_create_database_row | Create a new row | | appflowy_update_database_row | Update an existing row | | appflowy_delete_database_row | Delete a row |

Search Tools

| Tool | Description | |------|-------------| | appflowy_search | Full-text search across workspace content |

File Attachment Tools

| Tool | Description | |------|-------------| | appflowy_upload_file | Upload a file to AppFlowy storage | | appflowy_download_file | Download a file to your local machine | | appflowy_list_files | List files in storage | | appflowy_delete_file | Delete a file from storage | | appflowy_attach_file_to_document | Attach a file to a document |

📎 File Attachments

Upload files from your local machine and attach them to AppFlowy documents:

"Upload the file /home/user/report.pdf to my AppFlowy workspace"
→ Uses appflowy_upload_file

"Attach the uploaded report to the Sprint Review document"
→ Uses appflowy_attach_file_to_document

"Download the file with ID abc123 to /home/user/downloads"
→ Uses appflowy_download_file

Supported File Types

• Images: PNG, JPG, GIF, SVG, WebP
• Documents: PDF, DOCX, TXT, MD
• Code files: JS, TS, PY, JSON, YAML, etc.
• Archives: ZIP, TAR, GZ
• Any file type up to the configured max size (default: 50MB)

💡 Usage Examples

Find documentation

"Search in AppFlowy for documents about API architecture"
→ appflowy_search(query="API architecture")

Create meeting notes

"Create meeting notes for today's standup in AppFlowy"
→ appflowy_create_document(name="Standup - 2026-06-13")

Manage tasks

"Show me all pending tasks in the project database"
→ appflowy_read_database → filter by status

Upload and attach files

"Upload the design mockup.png and attach it to the Design Specs document"
→ appflowy_upload_file → appflowy_attach_file_to_document

🔧 Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Test with MCP Inspector
npm run inspector

🐛 Troubleshooting

| Problem | Solution | |---------|----------| | ECONNREFUSED | Check that AppFlowy Cloud is running and APPFLOWY_BASE_URL is correct | | Authentication failed | Verify email/password or regenerate JWT token | | Workspace not found | Run appflowy_list_workspaces to get valid IDs | | File upload too large | Increase APPFLOWY_MAX_FILE_SIZE_MB | | Token expired | The server auto-refreshes tokens; if issues persist, restart the IDE |

📄 License

MIT License — see LICENSE for details.

Made with ❤️ for the AppFlowy community

AppFlowy • GitHub • Discord