AFFiNE 工作區 MCP 可讓相容的 AI 用戶端搜尋筆記與白板文字、讀取文件。支援 Streamable HTTP 與 Bearer 標頭的用戶端可直接連線;支援本機 stdio 的用戶端則可使用本機橋接。
MCP 是讓 AI 助理連接外部工具與資料的開放標準。支援的 AFFiNE Cloud 與自架環境提供工作區端點。直接連線需要 Streamable HTTP 與 Authorization 標頭;僅支援 stdio 的用戶端可使用 mcp-remote 等本機橋接。
連線之後,助理可以在整個知識庫執行關鍵字與語意搜尋(白板也在搜尋範圍內)並讀取完整文件,權限就是你授予的範圍,一分不多。每個用戶端各自持有一張憑證,可以獨立輪換或撤銷,所以「讓 AI 看我的筆記」永遠不必變成「全部、永久」。
| 這是什麼 | 內建於 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}/mcpdoc_searchread_document獨立的唯讀服務,只讀取已發布的部落格文章與範本,不需要帳號或憑證。它無法讀取你的工作區或寫入文件,請勿向此端點傳送工作區憑證。
https://affine.pro/api/public/mcpsearch_public_contentread_public_content先在 AFFiNE 建立工作區憑證,再依使用的用戶端格式設定連線。
在 AFFiNE 中前往「設定」→「Integrations」→「MCP Server」。AFFiNE Cloud 與啟用 AI 功能的自架版都適用。
點「Create credential」,取個標籤(每個用戶端一張,例如「Claude Code」或「Cursor」),再選擇存取模式與到期日。預設為唯讀。
從 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 橋接只適用於能啟動本機程序的用戶端。
一行 CLI 指令加入 AFFiNE,之後任何工作階段都能請 Claude 搜尋或讀取你的工作區。
claude mcp add --transport http affine \
"https://app.affine.pro/api/workspaces/<workspace-id>/mcp" \
--header "Authorization: Bearer <your-credential>"將下方 URL 與 headers 加入 ~/.cursor/mcp.json。使用從自己工作區複製的端點與憑證;各用戶端的 JSON 格式不同。
{
"mcpServers": {
"affine": {
"url": "https://app.affine.pro/api/workspaces/<id>/mcp",
"headers": {
"Authorization": "Bearer <your-credential>"
}
}
}
}打開 Cline 的 MCP 設定,把 AFFiNE 加為遠端 Streamable HTTP 伺服器。
{
"mcpServers": {
"affine": {
"type": "streamableHttp",
"url": "https://app.affine.pro/api/workspaces/<id>/mcp",
"headers": {
"Authorization": "Bearer <your-credential>"
}
}
}
}此設定適用於能啟動本機 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 取得文件完整內容,遵循你目前的工作區權限。
create_document啟用時可由標題與 Markdown 本文建立文件;不支援插入資料庫區塊或圖片。
update_document啟用時以結構差異更新 Markdown 本文;不會更改標題,也不支援更新資料庫區塊或圖片。
update_document_meta啟用時更新文件標題。已核對的工具未提供其他中繼資料欄位。
一張憑證只到得了一個工作區,並套用你的權限。
撤銷任一用戶端的存取,不影響其他用戶端。
每張憑證建立時都會設定到期日。
舊權杖最多再有效 24 小時,若原到期時間更早則以該時間為準;撤銷也可能提早終止存取。
支援 MCP 的筆記工具越來越多,差別在於伺服器搜得到什麼、跑在哪裡、由誰掌控。以下與最常被拿來比較的兩種方案對照。
| AFFiNE | Notion MCP | Obsidian | |
|---|---|---|---|
| 官方內建 | 是第一方伺服器,內建於應用程式;憑證在工作區設定建立 | 是由 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 裡的官方 Model Context Protocol 端點,讓 Claude、Cursor、Cline 等 AI 助理透過標準且經驗證的 HTTP 連線,搜尋並讀取你某個 AFFiNE 工作區裡的文件。憑證在工作區設定中建立與管理,完全由你掌控。
免費。AFFiNE Cloud 與啟用 AI 功能的自架版都可以免費使用,連線本身不另外收費。
能。doc_search 同時涵蓋頁面文件與 Edgeless 白板:畫布上的文字會被索引,結果附帶區塊、元素或框架定位,助理能指出答案在白板的哪個位置。完整讀取回傳頁面內容,白板內容則經由搜尋浮現。這是多數純文字 MCP 伺服器做不到的。
支援。官方 MCP 端點在自架版上同樣可用,端點位於你自己的伺服器位址,設定步驟相同(設定 → Integrations → MCP Server),只要在主機上啟用 AI 功能即可。資料想留在自己手上的團隊,這是完整的一條路。
預設為唯讀。2026 年 10 月 26 日核對的實作將讀寫憑證建立與寫入工具限制在開發或 canary 環境,不能據此宣稱穩定版 Cloud 已提供。請透過環境的存取模式設定與 tools/list 確認實際功能。
請同時檢查傳輸及驗證方式。Claude Code、Cursor、Cline 支援 HTTP 與 Bearer 標頭。僅接受 OAuth 登入的連線介面無法使用這種手動建立的憑證。stdio 橋接只適用於能啟動本機程序的用戶端。
一張憑證只到得了一個工作區,並套用你的權限。 撤銷任一用戶端的存取,不影響其他用戶端。 每張憑證建立時都會設定到期日。 舊權杖最多再有效 24 小時,若原到期時間更早則以該時間為準;撤銷也可能提早終止存取。
最後更新: 2026年10月26日