Flexnote MCP 服務：在 Cursor 與 Codex 中訪問本地知識庫

在 Cursor、Codex 等開發環境中工作時，通常仍需查閱本地筆記中的結論、文獻摘錄或白板結構。若依賴複製貼上或切換至其他對話視窗，知識庫與當前工作流會被拆成兩套系統，上下文難以保持完整。

Flexnote 桌面端現已內建 MCP 服務（Model Context Protocol）。服務僅監聽本機 127.0.0.1。已支援該協議的客戶端（包括 Cursor、Claude Desktop、Codex）可直接檢索、讀取並寫入當前筆記庫。資料仍儲存在使用者裝置上，不會上傳至第三方筆記雲。

一、與應用內 Flexnote AI 的區別

MCP 是一項開放協議，用於向外部人工智慧客戶端宣告可呼叫的工具。客戶端獲取工具列表、按名稱發起呼叫，並接收 JSON 文本結果。模型由客戶端自行選擇，Flexnote 不介入其計費與供應商。

應用內的 Flexnote AI 運行於側欄對話：使用使用者在設定中填寫的 API Key，回答可附帶引用，Agent 亦可編輯白板。MCP 則將同一知識庫開放給外部開發工具，以便在編碼或寫作介面中直接操作日記、卡片、待辦與白板，而無需離開當前視窗。

二、能力範圍

可查詢當前工作空間中的卡片、日記、白板、待辦、標籤與收藏。寫入類工具需關閉「只讀模式」。畫布相關操作需提供白板 ID；若目標白板未開啟，Flexnote 將先行跳轉並等待畫布就緒後再執行，以避免客戶端請求超時。

三、啟用方式

MCP 為專業版功能，須登入有效會員賬號，且 Flexnote 桌面客戶端處於執行狀態。退出應用後，本機埠將關閉，外部客戶端無法連線。

1. 開啟 Flexnote → 設定 → MCP 服務。
2. 開啟服務。服務僅繫結本機迴環地址，預設埠為 39125。
3. 按客戶端型別複製配置：Cursor / Claude Desktop 使用 HTTP JSON；僅支援 command 啟動的客戶端使用 stdio 橋；Codex CLI 使用 TOML。
4. 將配置寫入對應客戶端。訪問令牌僅用於本機鑑權，請勿提交至公開程式碼倉庫或對外傳播。

建議同時確認以下選項：只讀模式僅開放查詢類工具，適用於接入驗證；亦可按工具關閉不希望外部模型呼叫的寫入能力。

四、接入 Cursor、Claude Desktop 與 Codex

Cursor / Claude Desktop

使用設定頁提供的 HTTP 配置。核心欄位為本機 URL 與 Bearer 令牌，示例如下：

{
  "mcpServers": {
    "flexnote": {
      "url": "http://127.0.0.1:39125/mcp",
      "headers": { "Authorization": "Bearer 你的令牌" }
    }
  }
}

Codex CLI

Codex CLI 通常通過 stdio 橋接：由 Node 執行 Flexnote 提供的指令碼，將標準輸入轉發至本機 HTTP 端點。設定頁可複製 TOML 配置並定位橋接指令碼。請在環境變數中設定 FLEXNOTE_MCP_URL 與 FLEXNOTE_MCP_TOKEN。

五、呼叫示例

連線成功後，無需記憶工具名稱，可直接使用自然語言。以下語句可用於驗證接入是否正常：

• 「當前 Flexnote 工作空間是哪一個？列出最近的白板和五張卡片，不要修改任何資料。」
• 「將這段結論追加到今天的日記。若當天日記不存在則建立。請勿儲存為普通筆記卡片。」
• 「新建一張筆記，標題為《MCP 試驗》，正文須以 Markdown 一級標題開頭。」
• 「在指定白板（提供 whiteboardId）上建立兩張便籤並建立連線，然後讀取畫布佈局。」
• 「列出待辦事項，並將其中一項標記為完成。」

寫入成功後，Flexnote 將在視窗中顯示提示。若存在對應實體，可選擇「檢視」開啟相應頁面；否則可選擇重新整理介面。提示預設保持顯示，直至使用者關閉。

六、安全說明

服務僅監聽本機地址。同一裝置上持有訪問令牌的其他程序亦可呼叫上述工具，請將令牌按憑據管理。如需作廢舊配置，可在設定中重新生成令牌，原配置立即失效。

一旦開放寫入類工具，外部模型即可修改知識庫。在驗證階段建議啟用只讀模式，或關閉建立、刪除及白板相關工具。MCP 僅作用於當前開啟的工作空間，操作前請確認空間選擇無誤。

七、適用範圍

• 僅使用瀏覽器、不執行桌面客戶端時，本機不存在 MCP 埠，無法接入。
• 本服務不是團隊共享閘道器，也不提供公網訪問，不適用於將筆記庫開放給其他成員。
• Flexnote 不以即時多人白板為產品方向，MCP 亦不提供該項能力。完整產品定位見 Flexnote 是什麼。

八、開始使用

請將桌面客戶端更新至包含 MCP 的版本，使用專業版賬號登入，在設定中啟用服務，並將配置寫入 Cursor 或 Codex。建議先以只讀模式完成檢索驗證，再開放寫入。客戶端下載見 下載頁；專業版說明見 定價。

若已在使用應用內知識庫 Agent，無需調整既有筆記方法。MCP 僅將同一本地知識庫接入外部開發工具。