Mi Note MCP

🚀 mi_note_mcp

mi_note_mcp 是一款基於 Model Context Protocol (MCP) 的小米雲筆記服務器實現方案。藉助該項目，支持 MCP 的助手（如 Claude、ChatGPT 桌面端等）能夠直接對雲端筆記進行讀取、搜索、創建和管理操作。同時，項目會在本地對接口結果進行緩存，並具備 Markdown/XML 互轉能力，確保大語言模型可以無縫處理筆記內容。

✨ 主要特性

• 讀取、搜索與緩存：支持列出、搜索、查看筆記詳情，同時自動維護本地緩存，有效減輕重複網絡請求的負擔。
• 完整的筆記編輯鏈路：提供創建、更新、刪除、移動筆記等常見操作，並且會自動同步資源狀態。
• 文件夾管理：支持列出、創建、重命名、刪除文件夾，還能按文件夾查看筆記。
• 富文本轉換：可在 Markdown 與小米筆記內部 XML 之間相互轉換，同時保留任務列表、圖片、粗體等格式。
• 圖片上傳：能夠將本地圖片上傳至小米雲端，並返回 minote://image/{fileId} 形式的可複用鏈接。
• MCP 資源暴露：暴露筆記、文件夾相關資源 URI，便於上下文補全與導航。

📦 安裝指南

環境要求

• Bun ≥ 1.1（開發測試使用 1.2.23）
• 一個可以訪問 https://i.mi.com/note 的小米賬號
• Node.js TypeScript 生態（僅在開發/類型檢查時需要）

安裝步驟

1. 安裝依賴

bun install

2. 配置憑據

服務啟動前需要準備配置文件，默認路徑為 ~/.mi-note-mcp.json，也可以通過環境變量 MI_NOTE_MCP_CONFIG 指定其他位置。

配置示例：

{
  "serviceToken": "YOUR_SERVICE_TOKEN",
  "userId": "YOUR_USER_ID",
  "passToken": "可選，增強登錄穩定性",
  "slh": "可選",
  "ph": "可選",
  "deviceId": "可選，用於與網頁保持一致",
  "cUserId": "可選",
  "uLocale": "zh_CN",
  "syncInterval": 30000,
  "baseUrl": "https://i.mi.com"
}

獲取方式建議在瀏覽器登錄 小米雲筆記 後，通過開發者工具複製請求頭中的 Cookie 字段（如 serviceToken、userId、passToken 等），並保證這些字段長期有效。syncInterval 以毫秒為單位，用於控制後臺增量同步頻率。

3. 啟動 MCP 服務器

bun run index.ts

啟動成功後，終端會輸出 mi-note-mcp server started。隨後即可在支持 MCP 的客戶端中把 mi_note_mcp 註冊為本地服務，按客戶端指引填寫命令與工作目錄。

📚 詳細文檔

MCP 工具與資源

工具（Tools）

資源（Resources）

緩存與同步機制

• 首次啟動會通過 /note/full/page 獲取全量數據並緩存到內存。
• 之後按照 syncInterval（默認 30 秒）調用增量同步接口更新筆記與文件夾狀態。
• 工具在執行寫操作後會主動刷新緩存並觸發資源更新，保證 MCP 客戶端側 UI 與上下文立即感知變化。
• 可以通過 NotesCache 的 refresh() 方法在代碼中強制刷新（大部分工具已自動調用）。

開發與測試

• 類型檢查（推薦在提交前運行）：

bun run tsc --noEmit --skipLibCheck

• 單元測試：

bun test

開發時建議遵循倉庫內現有的代碼風格與目錄結構，必要時參考 tests/ 下用例瞭解關鍵模塊行為。

常見問題

• 提示配置文件不存在：確認 ~/.mi-note-mcp.json 是否創建成功，或設置正確的 MI_NOTE_MCP_CONFIG。
• 返回 401/403：通常是 serviceToken、userId 等 cookie 過期，重新從網頁端複製並更新配置後重試。
• 圖片上傳失敗：檢查文件是否存在、MIME 類型是否正確，或網絡是否可訪問 i.mi.com。

如需擴展額外工具或資源，請優先複用現有客戶端與緩存邏輯，遵守項目的 KISS/YAGNI 原則。