MCP 整合

AFFiNE MCP 伺服器:把 AI 工具接上你的知識庫

AFFiNE 工作區 MCP 可讓相容的 AI 用戶端搜尋筆記與白板文字、讀取文件。支援 Streamable HTTP 與 Bearer 標頭的用戶端可直接連線;支援本機 stdio 的用戶端則可使用本機橋接。

  • 以工作區為範圍、可撤銷的憑證
  • Streamable HTTP + Bearer
  • GitHub 70K+ 顆星

讓相容的 AI 用戶端存取知識庫

MCP 是讓 AI 助理連接外部工具與資料的開放標準。支援的 AFFiNE Cloud 與自架環境提供工作區端點。直接連線需要 Streamable HTTP 與 Authorization 標頭;僅支援 stdio 的用戶端可使用 mcp-remote 等本機橋接。

連線之後,助理可以在整個知識庫執行關鍵字與語意搜尋(白板也在搜尋範圍內)並讀取完整文件,權限就是你授予的範圍,一分不多。每個用戶端各自持有一張憑證,可以獨立輪換或撤銷,所以「讓 AI 看我的筆記」永遠不必變成「全部、永久」。

AFFiNE MCP 伺服器一覽

這是什麼內建於 AFFiNE Cloud 與自架版的官方 Model Context Protocol 端點
端點POST /api/workspaces/{workspace-id}/mcp
傳輸方式Streamable HTTP(無狀態)
驗證Bearer 憑證(aff_mcp_v1. 前綴),在工作區設定中為每個用戶端各別建立
工具doc_search / read_document; READ_WRITE: development / canary
範圍一張憑證對應一個工作區,遵循你的文件權限
價格AFFiNE Cloud 與啟用 AI 功能的自架版皆免費

工作區連線或公開內容示範?

自己的工作區

連接 AFFiNE Cloud 或受支援的自架環境,需要工作區 Bearer 憑證並遵循文件權限。下列為唯讀預設工具,實際提供情況取決於部署環境。

https://app.affine.pro/api/workspaces/{workspace-id}/mcp
  • doc_search
  • read_document

公開網站內容

獨立的唯讀服務,只讀取已發布的部落格文章與範本,不需要帳號或憑證。它無法讀取你的工作區或寫入文件,請勿向此端點傳送工作區憑證。

https://affine.pro/api/public/mcp
  • search_public_content
  • read_public_content
Public content API (English)

連接相容的 MCP 用戶端

先在 AFFiNE 建立工作區憑證,再依使用的用戶端格式設定連線。

  1. 打開工作區的 MCP 設定

    在 AFFiNE 中前往「設定」→「Integrations」→「MCP Server」。AFFiNE Cloud 與啟用 AI 功能的自架版都適用。

  2. 建立憑證

    點「Create credential」,取個標籤(每個用戶端一張,例如「Claude Code」或「Cursor」),再選擇存取模式與到期日。預設為唯讀。

  3. 把設定貼進用戶端

    從 AFFiNE 複製端點與憑證。權杖只顯示一次。請依下方對應範例設定,不要假設所有用戶端接受相同 JSON。

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

AFFiNE 產生的連線格式;請依用戶端調整。自架環境使用自己的伺服器網址。

各用戶端的連線方式

請同時檢查傳輸及驗證方式。Claude Code、Cursor、Cline 支援 HTTP 與 Bearer 標頭。僅接受 OAuth 登入的連線介面無法使用這種手動建立的憑證。stdio 橋接只適用於能啟動本機程序的用戶端。

Claude Code

一行 CLI 指令加入 AFFiNE,之後任何工作階段都能請 Claude 搜尋或讀取你的工作區。

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

Cursor

將下方 URL 與 headers 加入 ~/.cursor/mcp.json。使用從自己工作區複製的端點與憑證;各用戶端的 JSON 格式不同。

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

Cline

打開 Cline 的 MCP 設定,把 AFFiNE 加為遠端 Streamable HTTP 伺服器。

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

Claude Desktop 等本機 stdio 用戶端

此設定適用於能啟動本機 stdio 程序的用戶端,需要第三方 mcp-remote 與受支援的 Node.js。這不是 Claude 網頁版的 OAuth 連接器。

{
"mcpServers": {
"affine": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://app.affine.pro/api/workspaces/<workspace-id>/mcp",
"--header",
"Authorization:${AFFINE_MCP_AUTH}"
],
"env": {
"AFFINE_MCP_AUTH": "Bearer <your-credential>"
}
}
}
}

接上之後,助理能做什麼

預設為唯讀。2026 年 10 月 26 日核對的實作將讀寫憑證建立與寫入工具限制在開發或 canary 環境,不能據此宣稱穩定版 Cloud 已提供。請透過環境的存取模式設定與 tools/list 確認實際功能。

唯讀

預設
doc_search
文件搜尋

跨工作區文件的關鍵字與語意搜尋,回傳限定範圍的段落,附頁面或畫布定位。不碰檔案、Blob 或網路。

read_document
讀取文件

以 ID 取得文件完整內容,遵循你目前的工作區權限。

讀寫

Development / canary
create_document
建立文件

啟用時可由標題與 Markdown 本文建立文件;不支援插入資料庫區塊或圖片。

update_document
更新文件

啟用時以結構差異更新 Markdown 本文;不會更改標題,也不支援更新資料庫區塊或圖片。

update_document_meta
更新文件屬性

啟用時更新文件標題。已核對的工具未提供其他中繼資料欄位。

以工作區為範圍

一張憑證只到得了一個工作區,並套用你的權限。

每個用戶端一張憑證

撤銷任一用戶端的存取,不影響其他用戶端。

內建到期機制

每張憑證建立時都會設定到期日。

權杖輪替

舊權杖最多再有效 24 小時,若原到期時間更早則以該時間為準;撤銷也可能提早終止存取。

AFFiNE 的 MCP 伺服器比較

支援 MCP 的筆記工具越來越多,差別在於伺服器搜得到什麼、跑在哪裡、由誰掌控。以下與最常被拿來比較的兩種方案對照。

AFFiNENotion MCPObsidian
官方內建是第一方伺服器,內建於應用程式;憑證在工作區設定建立是由 Notion 託管的官方遠端伺服器否社群外掛或第三方伺服器
可自行架設是同一個官方端點;在你的主機上啟用 AI 功能即可否現行伺服器僅託管;已棄用的舊開源版才能自架視情況預設在本機,遠端要自己動手
白板搜尋是搜尋會索引 Edgeless 畫布文字,回傳元素與框架定位否Notion 沒有原生白板否.canvas 檔只能讀成原始 JSON,沒有主流伺服器能搜尋
部署形態Cloud 或自架AFFiNE 內建官方端點;自架需啟用 AI 功能僅託管現行官方伺服器由 Notion 託管本機社群伺服器伴隨桌面版 Vault 執行
價格免費Cloud 與啟用 AI 功能的自架版皆免費核心免費連接應用搜尋與會議記錄需 Notion AI 方案免費應用程式與社群伺服器皆免費

比較基於 2026 年 8 月公開文件記載的能力。

Obsidian 基於 REST API 的 MCP 伺服器需要桌面版應用程式常駐執行。Obsidian 官方 CLI(2026)是官方自動化介面,但不是 MCP。

常見問題

AFFiNE 的 MCP 伺服器是什麼?

它是內建在 AFFiNE 裡的官方 Model Context Protocol 端點,讓 Claude、Cursor、Cline 等 AI 助理透過標準且經驗證的 HTTP 連線,搜尋並讀取你某個 AFFiNE 工作區裡的文件。憑證在工作區設定中建立與管理,完全由你掌控。

MCP 伺服器免費嗎?

免費。AFFiNE Cloud 與啟用 AI 功能的自架版都可以免費使用,連線本身不另外收費。

AI 也能搜尋白板嗎?

能。doc_search 同時涵蓋頁面文件與 Edgeless 白板:畫布上的文字會被索引,結果附帶區塊、元素或框架定位,助理能指出答案在白板的哪個位置。完整讀取回傳頁面內容,白板內容則經由搜尋浮現。這是多數純文字 MCP 伺服器做不到的。

自架的 AFFiNE 也支援嗎?

支援。官方 MCP 端點在自架版上同樣可用,端點位於你自己的伺服器位址,設定步驟相同(設定 → Integrations → MCP Server),只要在主機上啟用 AI 功能即可。資料想留在自己手上的團隊,這是完整的一條路。

可以只給唯讀權限嗎?

預設為唯讀。2026 年 10 月 26 日核對的實作將讀寫憑證建立與寫入工具限制在開發或 canary 環境,不能據此宣稱穩定版 Cloud 已提供。請透過環境的存取模式設定與 tools/list 確認實際功能。

哪些 AI 工具可以連線?

請同時檢查傳輸及驗證方式。Claude Code、Cursor、Cline 支援 HTTP 與 Bearer 標頭。僅接受 OAuth 登入的連線介面無法使用這種手動建立的憑證。stdio 橋接只適用於能啟動本機程序的用戶端。

存取安全怎麼確保?

一張憑證只到得了一個工作區,並套用你的權限。 撤銷任一用戶端的存取,不影響其他用戶端。 每張憑證建立時都會設定到期日。 舊權杖最多再有效 24 小時,若原到期時間更早則以該時間為準;撤銷也可能提早終止存取。

讓你的知識庫開始工作

在工作區設定建立一張憑證,你的 AI 工具今天就能用你自己的筆記回答問題。

最後更新: 2026年10月26日