AFFiNE MCP Server: connect AI tools to your knowledge base

AFFiNE ships a built-in Model Context Protocol server. The AI tools you already use, from Claude and Cursor to any MCP client, can search your workspace, whiteboards included, and read your documents over a standard, revocable, workspace-scoped connection. No bridge service, no plugin.

Open AFFiNE and connect View the source on GitHub

• Workspace-scoped, revocable credentials
• Works with any MCP client
• 71,384 GitHub stars

Your knowledge base, available to every AI tool

The Model Context Protocol (MCP) is the open standard that lets AI assistants talk to external tools and data. AFFiNE's official MCP server is built directly into AFFiNE Cloud and self-hosted instances: no separate service to install, no third-party bridge between your AI tools and your notes.

Once connected, an assistant can run keyword and semantic search across your knowledge base, whiteboards included, and read full documents, with exactly the permissions you grant and nothing more. Each client gets its own credential that you can rotate or revoke independently, so "my AI can see my notes" never has to mean "everything, forever".

AFFiNE MCP Server at a glance

Connect an MCP client in two minutes

Setup happens entirely inside AFFiNE. The app generates a ready-to-paste configuration for you.

1. Open your workspace's MCP settings
   In AFFiNE, go to Settings, then Integrations, then MCP Server. This works on AFFiNE Cloud and on self-hosted instances with AI features enabled.

2. Create a credential
   Click 'Create credential', give it a label (one per client, for example 'Claude Code' or 'Cursor'), then choose the access mode and an expiry. Read only is the default.

3. Copy the configuration into your client
   The token is shown once. Use 'Copy JSON' to grab a complete MCP configuration, endpoint URL and auth header included, and paste it into your client's MCP settings.

   {
     "mcpServers": {
       "affine_workspace_<workspace-id>": {
         "type": "streamable-http",
         "url": "https://app.affine.pro/api/workspaces/<workspace-id>/mcp",
         "headers": { "Authorization": "Bearer aff_mcp_v1...." }
       }
     }
   }

The exact configuration AFFiNE generates for you. On self-hosted instances the URL uses your own server address.

Client-by-client setup

AFFiNE's MCP server speaks standard streamable HTTP, so any MCP client can connect. Here are the four we get asked about most.

Claude Code

Add AFFiNE with one CLI command, then ask Claude to search or read your workspace from any session.

   claude mcp add --transport http affine \
     "https://app.affine.pro/api/workspaces/<workspace-id>/mcp" \
     --header "Authorization: Bearer <your-credential>"

Cursor

Paste the configuration from AFFiNE's 'Copy JSON' button into ~/.cursor/mcp.json. The format matches as-is.

   {
     "mcpServers": {
       "affine": {
         "url": "https://app.affine.pro/api/workspaces/<id>/mcp",
         "headers": {
           "Authorization": "Bearer <your-credential>"
         }
       }
     }
   }

Cline

Open Cline's MCP settings and add AFFiNE as a remote streamable HTTP server.

   {
     "mcpServers": {
       "affine": {
         "type": "streamableHttp",
         "url": "https://app.affine.pro/api/workspaces/<id>/mcp",
         "headers": {
           "Authorization": "Bearer <your-credential>"
         }
       }
     }
   }

Claude Desktop & other clients

Clients that don't support custom auth headers for remote servers can connect through the standard mcp-remote bridge.

   npx mcp-remote \
     "https://app.affine.pro/api/workspaces/<workspace-id>/mcp" \
     --header "Authorization: Bearer <your-credential>"

What a connected assistant can do

Capabilities depend on the access mode of the credential you create. Read only is the default; read and write is rolling out to workspaces progressively.

Read only

Default

• Document search
  doc_search
  Keyword and semantic search across workspace documents, returning bounded passages with page or canvas locators. Never files, blobs or the web.

• Read document
  read_document
  Fetch the full content of a document by ID, respecting your current workspace permissions.

Read and write

Rolling out

• Create document
  create_document
  Create a new document from a title and Markdown content, and get back its ID.

• Update document
  update_document
  Rewrite a document's body with structural diffing, so history is preserved and live collaborators are never disrupted.

• Update document metadata
  update_document_meta
  Update document properties such as the title.

Workspace-scoped A credential only ever reaches one workspace, with your permissions.

One credential per client Revoke any client's access without touching the others.

Expiry built in Every credential gets an expiry date when you create it.

Zero-downtime rotation Rotate a token and the old one stays valid for 24 hours.

How AFFiNE's MCP server compares

Plenty of note-taking tools speak MCP now. What differs is what the server can reach, where it runs, and who controls it. Here is how AFFiNE's built-in server compares with the two setups people ask about most.

Comparison reflects publicly documented capabilities as of August 2026.

Obsidian's REST-API-based MCP servers require the desktop app to be running. Obsidian's CLI (2026) is an official automation surface, but it is not MCP.

Frequently asked questions

What is the AFFiNE MCP server?

It is the official Model Context Protocol endpoint built into AFFiNE. It lets AI assistants such as Claude, Cursor and Cline search and read the documents in one of your AFFiNE workspaces over a standard, authenticated HTTP connection, using credentials you create and control in workspace settings.

Is the AFFiNE MCP server read-only?

Read only is the default access mode: connected assistants can search the workspace and read documents, but not change anything. A read-and-write mode, which adds creating documents and updating document content and metadata, is rolling out progressively. Where available, you choose the mode per credential when you create it.

Does the MCP server work with self-hosted AFFiNE?

Yes. The official MCP endpoint is available on self-hosted AFFiNE instances. On a self-hosted instance the endpoint lives on your own server address, and setup is identical: Settings, Integrations, MCP Server. AI features need to be enabled on the instance.

How is access secured?

Every credential is scoped to a single workspace and honors your existing document permissions. You create a separate credential per client, set an expiry when you create it, and can rotate or revoke any credential at any time. Rotation keeps the old token valid for up to 24 hours so you can update the client without downtime.

Which AI tools can connect to AFFiNE?

Any MCP client that supports remote servers over streamable HTTP: Claude Code, Cursor, Cline, LobeHub and many more. Clients without custom-header support for remote servers can connect through the standard mcp-remote bridge.

Can a connected AI search my whiteboards?

Yes. doc_search covers page documents and Edgeless whiteboards alike: text on the canvas is indexed, and results carry block, element or frame locators, so an assistant can point at exactly where on a whiteboard an answer lives. Full-document reads return page content; whiteboard content surfaces through search. Most note-taking MCP servers only see plain documents.

Why connect my notes to an AI assistant?

Grounding. An assistant that can search your actual notes answers from your knowledge: meeting decisions, project context, research. Because AFFiNE's server returns bounded passages with document locators, assistants can also cite exactly where an answer came from.

Keep exploring

[**AFFiNE AI**
The AI editor built into AFFiNE. Write, draw and present with AI.](/content/ai/index.html) [**Self-host AFFiNE**
Run the whole workspace, MCP server included, on your own infrastructure.](/content/self-host/index.html) [**Knowledge base software**
Why teams pick AFFiNE as their knowledge base.](/content/solutions/knowledge-base/index.html)

Put your knowledge base to work

Create a credential in your workspace settings and your AI tools can start answering from your own notes today.

Open AFFiNE Star on GitHub

Last updated: August 19, 2026