Heptabase MCP 與 CLI 完整整合指南：打造 AI Agent 的外部大腦知識庫
適用版本：Heptabase v1.91.0+（2026 年 4 月 22 日正式推出）
適用對象：使用 Claude Desktop、Claude Code、Cursor、Codex 或其他 AI Agent 的知識工作者
撰寫日期：2026-04-23
這是什麼？為什麼重要？
Heptabase CLI 是官方內建於桌面應用程式中的命令列工具，讓你可以透過終端機（Terminal）直接對知識庫進行搜尋、讀取、建立與管理 操作。
更重要的是，透過現代化的 heptabase mcp (Model Context Protocol) 協定與 CLI 支援，AI Agent 能夠** 程式化且具語意脈絡地存取** 你的整個個人知識庫——包括卡片、日記、標籤、白板關聯，甚至 AI Tutor 的課程與對話紀錄。
一句話總結：從此以後，你的 7,000+ 張卡片不再只能手動翻找，而是能透過終端指令與 heptabase mcp 伺服器，讓你的個人知識庫真正升級為 AI Agent 最強大的外接大腦。
第一步：安裝與啟用
前置條件
- Heptabase 桌面版已更新至 v1.91.0 以上
- macOS / Windows / Linux 系統環境
啟用步驟
- 打開 Heptabase 桌面版
- 點擊左下角頭像 → Settings
- 進入 AI Features 頁面
- 找到最下方的 CLI / MCP 區塊
- 將開關切換為 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 與 heptabase mcp 之前，先理解三個關鍵概念：
1. 所有輸出都是 JSON
CLI 的每個指令都回傳標準 JSON 格式，方便程式化處理與 AI 解析：
{
"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 與 MCP 教學文章
- 蘋果總裁班備課"
# 建立指定日期的日記
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>🎓 五、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、expectedOutcometopics[]：每個主題含子主題（subtopics），每個子主題標註學習狀態（notStarted|inProgress|covered）
🎓 七、AI Tutor — 課堂 (lesson)
列出課程中的課堂、讀取課堂計畫、查看對話紀錄。
# 列出某課程的所有課堂
heptabase lesson list <courseId>
# 讀取課堂計畫與產出物
heptabase lesson read <lessonId>
# 讀取課堂對話紀錄（含分頁）
heptabase lesson list-messages <lessonId> --offset 0 --limit 50lesson 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) 伺服器架構。Model Context Protocol 是由 Anthropic 推動的開放式標準協定，核心目的在於讓 LLM 能夠以統一、標準化、高安全性的方式，與外部資料庫及工具進行即時上下文（Context）交互。
為什麼必須啟用 Heptabase MCP 整合？
傳統的知識管理工具在與 AI 協作時，通常面臨「斷裂的上下文」問題——使用者必須手動複製筆記內容給 AI，或是仰賴簡易的 RAG（檢索增強生成）抓取片面文字。透過 heptabase mcp，AI 代理能直接感知整個知識圖譜的網狀關聯：
- 雙向語意關聯與圖譜推理：heptabase mcp 不單單檢索單張卡片，還能沿著雙向連結、白板板塊（Whiteboard Sections）與標籤維度，將相關脈絡一次餵給 LLM，使推論結果更具原創性與深度。
- 精細化權限與 OAuth 授權安全：heptabase mcp 採用現代化 OAuth 2.0 授權標準，可針對讀取範圍（Scope）進行嚴格隔離，防止敏感個人日記或機密專案意外暴露給外部代理。
- 即時同步與低延遲通訊：相較於本地 Shell 指令的排程呼叫，heptabase mcp 透過常駐協定通道傳輸結構化 JSON-RPC，大幅降低對話往返延遲。
Heptabase MCP 設定與 Claude Desktop 配置教學
要將 heptabase mcp 串接至 Claude Desktop 或支援 MCP 的開發環境中，只需在設定檔（claude_desktop_config.json）中加入官方提供的 MCP 連接配置：
{
"mcpServers": {
"heptabase": {
"command": "heptabase",
"args": ["mcp", "serve"]
}
}
}設定完成並重啟 Claude Desktop 後，你便能在右下角看到 Heptabase MCP 的連線指示燈亮起。此時 Claude 將獲得一系列原生工具（Tools），例如 search_cards、read_card_content、create_journal_entry 等。你可以直接在對話中下達高階指令：
「請透過 heptabase mcp 檢索我最近一週在『AI 產品架構』標籤下的所有卡片，並幫我整理成一份 1,000 字的產品評估報告。」Heptabase CLI vs. Heptabase MCP：兩者有何不同？
許多知識工作者會好奇：既然已經有 CLI，為什麼還需要 heptabase mcp？以下是兩者的定位比較：
| 比較維度 | Heptabase CLI | Heptabase MCP |
|---|---|---|
| 主要使用情境 | 本地終端腳本、自動化 Bash 批次匯入、Cron Job 排程 | Claude Desktop、Cursor 等對話型 AI Agent 深度上下文整合 |
| 通訊協定 | 本地 HTTP 伺服器 (127.0.0.1) + CLI 封裝 | 標準 Model Context Protocol (JSON-RPC) |
| 離線可用性 | 完全離線（需開啟桌面 App） | 支援本地程序模式與雲端 API 授權模式 |
| AI 自主呼叫難易度 | 需透過 Shell 工具執行指令並解析字串 | 原生 Tool Use，AI 可自主決定何時檢索與寫入 |
常見問題
Q：使用 Heptabase MCP 是否需要保持網路連線？
A：若是採用本地 Desktop App 模式的 heptabase mcp 伺服器，可在本機離線運作；但若是採用雲端 OAuth 授權與遠端 API 端點，則需要保持網路連線以進行身份驗證與資料同調。
Q：CLI 有 API 限流嗎？
A：本地通訊目前沒有硬性限制，但建議避免高頻非同步寫入（如每秒數十次），以確保 ProseMirror 資料庫寫入的完整性。
Q：可以用 CLI 或 MCP 建立視覺化白板嗎？
A：目前 v0.1.0 階段主要支援 card、note、journal、tag、course、goal、lesson 等資料節點操作，白板畫布的座標排版功能將在未來版本陸續開放。
Q：journal create 回傳 409 衝突錯誤怎麼辦？
A：這代表該日期已存在日記卡片。請改用 heptabase journal append <date> 進行內容追加。
Q：如何重新啟用或重設 Heptabase MCP 權限？
A：前往 Settings > AI Features > CLI / MCP，關閉開關後再次啟用，並確認終端機 PATH 路徑配置無誤即可。
完整指令速查表
| 指令 | 說明 |
|---|---|
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 的推出，代表個人知識管理（PKM）正式邁入「可程式化」與「語意自主推理」的新紀元。你不再只是知識的手動整理者，而是能夠建構一個具備主動記憶與執行能力的個人專屬 AI Agent 系統。
👉 善用 heptabase mcp 與 CLI，讓你的萬張卡片庫成為 AI 最強大的智慧外腦！
撰寫：CTO Antigravity | 基於 Heptabase v1.91.0 官方 CLI & MCP 實測 | 2026-04-23