Heptabase MCP 與 CLI 完整指南：用 Model Context Protocol 打造 AI Agent 知識庫自動化工作流

適用版本：Heptabase v1.91.0+（2026 年 4 月 22 日正式推出）

適用對象：使用 Claude Code、Cursor、Codex 或其他 AI Coding Agent 的知識工作者

撰寫日期：2026-04-23

這是什麼？為什麼重要？

Heptabase CLI 是官方內建於桌面應用程式中的命令列工具，讓你可以透過終端機（Terminal）直接對知識庫進行搜尋、讀取、建立與管理操作。

更重要的是，它讓 AI Agent 能夠程式化存取你的整個知識庫——包括卡片、日記、標籤，甚至 AI Tutor 的課程與對話紀錄。

一句話總結：從此以後，你的 7,000+ 張卡片不再只能用手動翻找，而是可以用一行指令搞定。此外，搭配全新的 heptabase mcp 協定，你的知識庫將成為 AI 最強大的外接大腦。

第一步：安裝與啟用

前置條件

Heptabase 桌面版已更新至 v1.91.0 以上
macOS 系統（Windows/Linux 操作類似）

啟用步驟

打開 Heptabase 桌面版
點擊左下角頭像 → Settings
進入 AI Features 頁面
找到最下方的 CLI 區塊
將開關切換為 Enabled
系統會彈出提示：

Enable the "heptabase" command
Add "/usr/local/bin" to your PATH, then reopen your terminal.

點擊 Done

驗證安裝

打開終端機，輸入：

heptabase --version

應該看到：

0.1.0

再確認 CLI 伺服器就緒：

heptabase start

成功回應：

{
  "status": "ready",
  "startedDesktopApp": false
}

注意：CLI 需要 Heptabase 桌面版正在執行才能使用。heptabase start 會自動啟動 App（如果尚未開啟）。

核心概念

在使用 CLI 之前，先理解三個關鍵概念：

1. 所有輸出都是 JSON

CLI 的每個指令都回傳 JSON 格式，方便程式化處理：

{
  "results": [...],
  "total": 7017,
  "offset": 0,
  "limit": 20
}

2. 寫入用 Markdown，讀取得到 ProseMirror JSON

操作	格式
`create`（建立）	Markdown ✅
`append`（追加）	Markdown ✅
`read`（讀取）	ProseMirror JSON
`save`（覆蓋）	ProseMirror JSON + contentMd5

實務建議：日常使用以 create 和 append 為主（直接寫 Markdown），避免直接操作 ProseMirror JSON。

3. 衝突偵測機制

save 操作需要提供 --content-md5（從最近一次 read 取得），防止多端編輯時的資料覆蓋。

完整指令集

📋 一、卡片管理 (card)

管理所有類型的卡片（筆記、PDF、日記、圖片、影片等）。

列出 / 搜尋卡片

# 列出最近更新的 20 張卡片（預設）
heptabase card list

# 搜尋關鍵字
heptabase card list -q "AI Agent"

# 只顯示筆記類型的卡片
heptabase card list --card-types note

# 多種類型篩選
heptabase card list --card-types "note,pdf,journal"

# 按建立時間排序（由新到舊）
heptabase card list --sort createdTime --direction descending

# 分頁：取第 21-40 筆
heptabase card list --offset 20 --limit 20

# 組合：搜尋「教學」相關筆記卡，取前 5 筆
heptabase card list -q "教學" --card-types note --limit 5

回傳格式：

{
  "results": [
    {
      "id": "015f4e9f-bbe1-42bc-...",
      "objectType": "note",
      "title": "AI 問題建模任務卡",
      "createdTime": "2026-04-22T...",
      "lastEditedTime": "2026-04-22T..."
    }
  ],
  "total": 7017,
  "offset": 0,
  "limit": 5
}

可用卡片類型：note、pdf、journal、highlightElement、source、image、video、audio、web

排序欄位：title、lastUpdatedTime（預設）、createdTime

刪除與還原卡片

# 軟刪除（移至回收桶）
heptabase card trash <cardId>

# 從回收桶還原
heptabase card restore <cardId>

📝 二、筆記卡片 (note)

建立、讀取、儲存與追加筆記卡片。

建立新筆記

# 用 Markdown 直接建立（第一行 # 標題會成為卡片標題）
heptabase note create -c "# 會議記錄 2026-04-23

## 議題
- AI 導入進度
- 下季度目標

## 決議
1. 優先完成 Heptabase 整合
2. 建立自動化知識同步流程"

回傳：

{
  "id": "24dff0b3-de1d-4d82-...",
  "title": "會議記錄 2026-04-23"
}

從檔案建立筆記

# 將本地 Markdown 檔案匯入為卡片
heptabase note create -f ./meeting_notes.md

讀取筆記

heptabase note read <cardId>

追加內容

# 在既有卡片末尾追加內容
heptabase note append <cardId> -c "## 補充
- 新增一條行動項目"

# 從檔案追加
heptabase note append <cardId> -f ./additional_notes.md

覆蓋儲存（進階）

# 先讀取取得 contentMd5
heptabase note read <cardId>

# 再用 ProseMirror JSON 覆蓋（需提供 md5 防衝突）
heptabase note save <cardId> --content-md5 "e296d763cc..." -f ./new_content.json

📔 三、日記 (journal)

按日期建立、讀取與追加日記。

建立日記

# 建立今天的日記
heptabase journal create -c "# 今日重點
- 完成 Heptabase CLI 教學文章
- 蘋果總裁班備課"

# 建立指定日期的日記
heptabase journal create -d 2026-04-23 -c "今日行程：Yvonne 教學 + 蘋果總裁班"

# 從檔案建立
heptabase journal create -d 2026-04-23 -f ./daily_note.md

注意：如果該日期已有內容，會回傳 409 錯誤。改用 append 追加。

讀取日記

heptabase journal read 2026-04-23

追加日記

# 在當日日記末尾追加
heptabase journal append 2026-04-23 -c "## 晚間補充
今天最大的收穫是..."

# 從檔案追加
heptabase journal append 2026-04-23 -f ./evening_notes.md

🏷️ 四、標籤管理 (tag)

建立、列出、新增與移除標籤。

列出所有標籤

# 列出全部標籤
heptabase tag list

# 按名稱篩選（不區分大小寫）
heptabase tag list --name-filter "教學"

建立新標籤

heptabase tag create --name "AI工作流"

如果標籤已存在，回傳 409 錯誤。

為卡片加標籤

# 用卡片 ID
heptabase tag add --card-id <cardId> --tag-name "AI工作流"

# 為日記加標籤（直接用日期作為 card-id）
heptabase tag add --card-id 2026-04-23 --tag-name "教學日"

亮點：如果標籤不存在，tag add 會自動建立。

列出標籤下的卡片

heptabase tag cards <tagId>

移除標籤

heptabase tag remove --card-id <cardId> --tag-id <tagId>

hr />

🎓 五、AI Tutor — 學習目標 (goal)

查看 AI Tutor 的頂層學習目標。

heptabase goal list

回傳範例：

{
  "goals": [
    {
      "id": "e0a165e6-...",
      "title": "打造 AI 企業培訓產品",
      "description": "將 Claude CoWork 概念轉化為...",
      "type": "general",
      "createdTime": "2026-04-01T...",
      "courses": [
        { "id": "6833fe94-...", "title": "4 小時課程產品化設計" }
      ]
    }
  ]
}

📚 六、AI Tutor — 課程 (course)

列出與讀取 AI Tutor 課程大綱。

# 列出所有課程
heptabase course list

# 讀取課程大綱（含主題、子主題、學習進度）
heptabase course read <courseId>

course read 回傳包含：

courseId、title、overview、expectedOutcome
topics[]：每個主題含子主題（subtopics），每個子主題標註學習狀態（notStarted | inProgress | covered）

🎓 七、AI Tutor — 課堂 (lesson)

列出課程中的課堂、讀取課堂計畫、查看對話紀錄。

# 列出某課程的所有課堂
heptabase lesson list <courseId>

# 讀取課堂計畫與產出物
heptabase lesson read <lessonId>

# 讀取課堂對話紀錄（含分頁）
heptabase lesson list-messages <lessonId> --offset 0 --limit 50

lesson list-messages 回傳：

{
  "lessonId": "...",
  "messages": [
    {
      "id": "...",
      "role": "user",
      "contentMarkdown": "我想了解如何...",
      "createdTime": "...",
      "createdBy": "user"
    },
    {
      "id": "...",
      "role": "assistant",
      "contentMarkdown": "根據你的學習目標...",
      "createdTime": "...",
      "createdBy": "ai"
    }
  ],
  "total": 42,
  "hasMore": false
}

實戰範例

範例 1：每日知識同步流程

# 1. 確認 CLI 就緒
heptabase start

# 2. 今日日記追加
heptabase journal append 2026-04-23 -c "## 晚間回顧
今天完成了三堂教學，核心收穫是..."

# 3. 將本地筆記匯入為卡片
heptabase note create -f ./teaching_notes.md

# 4. 為新卡片加標籤
heptabase tag add --card-id <剛建立的卡片ID> --tag-name "教學筆記"

範例 2：搜尋知識庫中的特定內容

# 搜尋所有關於「問題建模」的卡片
heptabase card list -q "問題建模" --limit 10

# 搜尋所有 PDF 類型的卡片
heptabase card list --card-types pdf --limit 50

# 搜尋最近建立的筆記
heptabase card list --card-types note --sort createdTime --limit 5

範例 3：AI Tutor 課程回顧

# 查看所有學習目標
heptabase goal list

# 取得某課程的大綱
heptabase course read 6833fe94-f20b-43b3-801b-ee413f9ea338

# 查看該課程的課堂列表
heptabase lesson list 6833fe94-f20b-43b3-801b-ee413f9ea338

# 讀取特定課堂的對話紀錄
heptabase lesson list-messages <lessonId> --limit 100

範例 4：批次匯入多個檔案

# 用 shell 迴圈將資料夾中的所有 .md 檔案匯入為卡片
for file in ./notes/*.md; do
  echo "匯入: $file"
  heptabase note create -f "$file"
done

與 AI Agent 整合

Claude Code / Cursor

在你的 AI Agent 中，可以直接呼叫 CLI 指令來存取知識庫：

「請幫我搜尋知識庫中關於『AI 工作流』的所有卡片」
→ AI 執行：heptabase card list -q "AI 工作流"

「請把這份會議紀錄存入 Heptabase」
→ AI 執行：heptabase note create -f ./meeting.md

「請在今天的日記追加這段反思」
→ AI 執行：heptabase journal append 2026-04-23 -c "..."

Heptabase MCP (Model Context Protocol) 深度整合指南

除了上述本地端的 CLI 工具之外，Heptabase 更進一步支援了強大的 heptabase mcp (Model Context Protocol) 伺服器整合。這項由 Anthropic 推出的開放標準，旨在讓 AI 系統（例如 Claude 3.5 Sonnet）能夠以安全、統一且高度結構化的方式，直接讀取外部資料來源與上下文。

為什麼你應該啟用 Heptabase MCP 整合？

過去 AI Agent 在存取你的個人筆記時，往往需要透過手動複製貼上，或是依賴不夠彈性的 API 串接。透過 heptabase mcp，AI 能夠將你的 Heptabase 知識庫視為一整個結構完整的「外接大腦」：

語意上下文推理：AI 不僅能讀取單張筆記，還能透過 heptabase mcp 深入解析卡片之間的雙向連結、白板關聯以及標籤，進而給出更精準、更符合個人脈絡的推論。
安全授權存取：heptabase mcp 採用標準的 OAuth 雲端安全授權協定，讓你能完全掌握哪些 AI 工具可以存取你的知識庫，確保商業機密與個人隱私不外洩。
雲端與本地互補：本地 CLI 適合離線環境下的快速 Shell 自動化批次處理；而 heptabase mcp 則更適合整合至 Claude Desktop 或其他支援 MCP 的高階 AI 代理（AI Agents）之中，實現無縫的語意寫作。

你可以透過 Heptabase 官方提供的 MCP 端點：https://api.heptabase.com/mcp 進行配置。一旦在你的 AI Agent 設定檔中啟用 heptabase mcp，你就能直接在對話中對 AI 下達複雜的跨卡片研究與整合任務。

常見問題

Q：CLI 是否需要網路連線？

A：不需要。CLI 透過本地 HTTP 伺服器（127.0.0.1）與 App 通訊，完全離線運作。但若是使用 heptabase mcp 的雲端授權功能，則需要保持網路連線以進行身份驗證。

Q：CLI 有 API 限流嗎？

A：目前沒有明確的速率限制，但建議避免高頻呼叫（如每秒數十次）。

Q：可以用 CLI 建立白板嗎？

A：目前不支援。v0.1.0 僅支援 card、note、journal、tag、course、goal、lesson 操作。

Q：`journal create` 回傳 409 怎麼辦？

A：該日期已有內容。改用 heptabase journal append 追加。

Q：如何重新登入或重設 CLI？

A：到 Settings > AI Features > CLI，關閉再重新啟用即可。

完整指令速查表

指令	說明
`heptabase start`	啟動 App 並等待 CLI 就緒
`heptabase card list [options]`	列出 / 搜尋卡片
`heptabase card trash`	刪除卡片至回收桶
`heptabase card restore`	從回收桶還原
`heptabase note create -c / -f`	建立筆記卡
`heptabase note read`	讀取筆記（ProseMirror JSON）
`heptabase note save`	覆蓋筆記（需 contentMd5）
`heptabase note append -c / -f`	追加筆記內容
`heptabase journal create [-d date] -c / -f`	建立日記
`heptabase journal read`	讀取日記
`heptabase journal save`	覆蓋日記（需 contentMd5）
`heptabase journal append -c / -f`	追加日記內容
`heptabase tag list [--name-filter]`	列出標籤
`heptabase tag create --name`	建立標籤
`heptabase tag cards`	列出標籤下的卡片
`heptabase tag add --card-id --tag-name`	為卡片加標籤
`heptabase tag remove --card-id --tag-id`	移除標籤
`heptabase goal list`	列出 AI Tutor 學習目標
`heptabase course list`	列出 AI Tutor 課程
`heptabase course read`	讀取課程大綱
`heptabase lesson list`	列出課堂
`heptabase lesson read`	讀取課堂計畫
`heptabase lesson list-messages`	讀取對話紀錄

結語

Heptabase CLI 與 heptabase mcp 的推出，代表個人知識管理正式進入「可程式化」與「語意推理」的新時代。你不再只是知識的消費者或手動整理者，而是可以讓 AI Agent 幫你自動搜尋、深度解讀、自動建卡的系統架構設計者。

👉 你的知識庫，現在是你的 AI 可以直接利用 heptabase mcp 完美讀取的終極大腦。

撰寫：CTO Antigravity | 基於 Heptabase v1.91.0 官方 CLI & MCP 實測 | 2026-04-23

蔡正信-數位教練

我是一位專精於數位轉型與AI應用的教練，致力於協助中高齡族群與企業主有效運用科技工具提升生產力。

蔡教練聯繫方式：https://rdcoach.pse.is/62uqz2

手機：0988-515-413

Line官方帳號2.0 : @rd.coach https://lin.ee/n4T9CGA
群英企業管理顧問股份有限公司
資訊顧問電子郵件：[email protected]

跨代際溝通 × AI賦能教學：
結合AI應用、數位工具教學與熟齡學習經驗，專注於中高齡與中小企業的數位轉型輔導，擅長從0到1建構數位素養。

實戰導向 × 客製培訓：
15年數位教學經驗，服務鴻海、1111人力銀行、台南大學、瓦城集團等，設計實用導向的教學模組，強調易學、可複製。

工具整合 × 工作流設計：
善用Evernote、Heptabase、Telegram等多款工具，打造AI第二大腦與一元筆記系統，協助學員從資訊收集到知識轉化。

行動導向 × 教學有感：
500+場講座與工作坊，專注學員實作與成果回報，推動「數位生活力」與「AI生活實驗室」教學風格。

預見未來 × 實踐智慧：
關注生成式AI與數位倫理發展，推動AI工具於科研、商業、教育場域的實作應用，擘劃AI助理與智慧工作未來藍圖。