AFFiNE MCP Server

affine-mcp-server (v2.1.0, MIT) verbindet AI-Assistenten mit AFFiNE Workspaces über das Model Context Protocol. 85 kanonische Tools für Dokumente, Datenbanken, Edgeless Canvas, Kommentare, Organisation und mehr.

Warum

AFFiNE hat keine öffentliche REST API. Der MCP Server überbrückt dies — AI-Agenten (OMP, Claude, Codex, Cursor) können programmatisch lesen, schreiben und Workspaces verwalten. Für die OMP-Tool-Umgebung siehe OMP Harness.

Setup für unsere Instanz

Option A: stdio (lokal)

npm i -g affine-mcp-server
affine-mcp login
# → Base URL: https://a.freundeskreis.family
# → Auth: email/password oder API token
affine-mcp status
affine-mcp doctor

Option B: Docker (HTTP-Endpoint)

docker run -d \
  -p 3100:3000 \
  -e MCP_TRANSPORT=http \
  -e AFFINE_BASE_URL=https://a.freundeskreis.family \
  -e AFFINE_API_TOKEN=ut_your_token \
  -e AFFINE_MCP_AUTH_MODE=bearer \
  -e AFFINE_MCP_HTTP_TOKEN=your-strong-secret \
  ghcr.io/dawncr0w/affine-mcp-server:latest

Client-Konfiguration

{
  "mcpServers": {
    "affine": {
      "command": "affine-mcp"
    }
  }
}

Tool-Katalog (85 Tools)

Workspace (7)

list_workspaces, get_workspace, create_workspace, update_workspace, delete_workspace, list_workspace_tree, get_orphan_docs

Organisation (12)

list_collections, get_collection, create_collection, update_collection, update_collection_rules, delete_collection, add_doc_to_collection, remove_doc_from_collection, list_organize_nodes, create_folder, create_workspace_blueprint, rename_folder, delete_folder, move_organize_node, add_organize_link, delete_organize_link

Dokumente — Discovery (9)

list_docs, list_tags, search_docs, list_docs_by_tag, get_doc, read_doc, get_capabilities, analyze_doc_fidelity, list_children

Dokumente — CRUD (6)

create_doc, create_doc_from_markdown, inspect_template_structure, instantiate_template_native, move_doc, delete_doc

Dokumente — Content Editing (6)

update_doc_title, append_block, create_semantic_page, append_semantic_section, append_markdown, replace_doc_with_markdown

Dokumente — Tags (3)

create_tag, add_tag_to_doc, remove_tag_from_doc

Dokumente — Export (2)

export_doc_markdown, export_with_fidelity_report

Publish (2)

publish_doc, revoke_doc

Database (7)

compose_database_from_intent, add_database_column, add_database_row, delete_database_row, read_database_columns, read_database_cells, update_database_row

Spaltentypen: rich-text, select, multi-select, number, checkbox, link, date

Edgeless Canvas (8)

Tool	Funktion
get_edgeless_canvas	Gesamte Canvas lesen: Blöcke + Surface-Elemente
add_surface_element	Shapes, Connectors, Text, Groups hinzufügen
list_surface_elements	Alle Surface-Elemente auflisten
update_surface_element	Element partiell aktualisieren
delete_surface_element	Element löschen
update_frame_children	Frame-Inhalt komplett ersetzen
update_edgeless_block	Note/Frame/Text repositionieren
delete_block	Block löschen

Canvas-Konzept: Zwei Ebenen — Top-Level-Blöcke (note, frame, edgeless-text) mit prop:xywh und die Surface-Ebene (affine:surface) mit Shapes, Connectors, Canvas-Text und Groups.

append_block Layout-Helpers:

• stackAfter: { blockId, direction, gap } — Relative Positionierung
• childElementIds — Frame auto-sizing um Inhalt
• markdown — Note mit Markdown-Inhalt und auto-geschätzter Höhe

Kommentare (5)

list_comments, create_comment, update_comment, delete_comment, resolve_comment

History, Users, Notifications, Blobs (10+)

Version history, user management, access tokens, notifications, blob storage — vollständiger Katalog in der Tool Reference.

Tool-Profile (Least Privilege)

Profil	Scope
full	Alle 85 Tools (Standard)
read_only	Nur Lese-Tools + Export
core	Discovery + Basic Authoring + Tags + DB
authoring	Non-destructive Create/Edit

# Einschränken via Env-Variable
AFFINE_TOOL_PROFILE=core
AFFINE_DISABLED_GROUPS=comments,history,blobs
AFFINE_DISABLED_TOOLS=delete_workspace,delete_doc

Workflow-Rezepte

1. Workspace entdecken

list_workspaces → list_docs → read_doc

2. Dokument erstellen und einordnen

search_docs → create_doc → move_doc → list_children

3. Datenbank aufbauen

read_doc → read_database_columns → add_database_column → add_database_row → read_database_cells

4. Canvas-Diagramm bauen

create_doc → add_surface_element (Shapes) → add_surface_element (Connectors) → append_block(type="frame", childElementIds=[...]) → get_edgeless_canvas

5. Template klonen

inspect_template_structure → instantiate_template_native

Edgeless Canvas Cookbook

Komplettes Beispiel: Auth-Flow-Diagramm mit 4 Shapes, 3 Connectors, Frame mit Auto-Sizing:

┌─ Frame "Auth Flow" ──────────────────────────────┐
│  [ User ] ──authenticate─→ [ Auth Service ]      │
│                                  │                │
│                            ──verify─→             │
│                                  │                │
│                            [ Database ]           │
│                                                   │
│                            [ Cache ] ←─session──  │
└───────────────────────────────────────────────────┘
    [ Epilogue note — auto-placed below ]

Jeder Schritt ist ein einzelner MCP-Tool-Call. Details: Edgeless Canvas Cookbook

Auth für Self-Hosted

Methode	Empfohlen für
API Token	Automation, stabil
Email/Password	Self-hosted, interaktiv
Cookie	Browser-Session reuse

Priorität: Token → Cookie → Email/Password

See also

• AFFiNE Workspace
• OMP Harness
• Skills & Integrations
• Quartz Wiki
• 🚀 Cheat Sheet
• Meta Hub
• Technik
• Plesk & Subdomains