使用 ChatGPT、Codex、Claude 或 Claude Code？ 建議直接安裝官方 Heptabase plugin，請參考在 ChatGPT 與 Codex 中使用 Heptabase 或在 Claude 與 Claude Code 中使用 Heptabase。本頁的設定方式適用於其他 AI 服務，或想手動連接的情況。

Heptabase MCP（Model Context Protocol）讓 AI 助理直接操作你的 Heptabase 工作區：搜尋及閱讀卡片、日誌、白板與標籤資料庫，撰寫筆記，把檔案和連結存成卡片，整理標籤，處理 Inbox，以及排版白板。

使用 MCP 需要 Heptabase Pro、Premium、Premium+ 訂閱或有效試用，唯讀連線也一樣。

AI 助理可以做什麼

搜尋與閱讀：用關鍵字或語意搜尋，閱讀卡片、日誌、白板、標籤資料庫、PDF、圖片、劃記與反向連結。
撰寫：建立及編輯筆記卡片與日誌，可以加入圖片、影片、音訊與附件。
存下檔案與連結：從檔案或網址建立 PDF、圖片、音訊、影片、網頁與 YouTube 卡片。
整理：建立及編輯標籤資料庫、把卡片加入或移出資料庫、設定卡片屬性、建立標籤群組、移動標籤，以及把卡片移到垃圾桶或還原。
處理 Inbox：讀取 Inbox、把卡片加入 Inbox、把項目標成完成或設定提醒，以及移除你加入的項目。
遵循 Space Instructions：讀取你為 AI 在這個空間怎麼工作所訂的規則，以及把一張卡片設為 Space Instructions。
操作白板：建立白板、區塊、連線與心智圖，並移動、對齊、縮放、變更顏色或移除物件。
在對話中顯示：在對話中顯示卡片，或直接在 ChatGPT、Claude、Codex，以及 Claude 桌面 app 裡的 Claude Code 打開白板。

完整的工具清單請參考 MCP 工具參考。

有些操作需要開著 Heptabase

編輯白板、編輯及查詢標籤資料庫、把卡片移出標籤資料庫、重新命名，以及讀取反向連結，都在 Heptabase app 裡執行。進行這些操作時，請開著 Heptabase 桌面 app 或網頁版，並登入同一個帳號。透過 ChatGPT 或 Claude 連接時，AI 助理也可以直接在對話裡打開 Heptabase，Codex 與 Claude 桌面 app 裡的 Claude Code 也一樣。行動版 app 無法執行這些操作。

開著 Heptabase 時，AI 助理也會從 app 讀取內容，所以讀得到還沒同步的編輯。其他操作都不需要開著 app。

連接 AI 服務

選擇你的 AI 服務：ChatGPT · Claude Code · Cursor · Antigravity CLI · 其他服務

ChatGPT：自訂 MCP 應用程式

官方 plugin 的設定比較簡單。只有想使用自訂 MCP 應用程式時，才需要以下步驟。自訂 MCP 應用程式需要 Developer mode，是否可用取決於你的 ChatGPT 方案或工作區，而且只能在 ChatGPT 網頁版設定。

開啟 ChatGPT 網頁版並登入。
開啟 Settings → Apps → Advanced Settings，啟用 Developer mode。
回到 Apps 建立自訂應用程式。如果沒有這個選項，請確認已啟用 Developer mode，且你的方案或工作區支援自訂 MCP 應用程式。
填寫以下欄位：
- Name：任意名稱，例如 Heptabase。
- MCP Server URL：https://api.heptabase.com/mcp
- Authentication：OAuth
- Icon（選填）：Heptabase logo。
視需要登入 Heptabase，然後點選 Allow。
想讓 ChatGPT 使用 Heptabase 時，在對話中選擇這個應用程式。

Claude Code

官方 plugin 的設定比較簡單。若要手動連接，請在終端機執行：

claude mcp add --transport http heptabase-mcp https://api.heptabase.com/mcp

接著啟動 Claude Code，輸入 /mcp，選擇 heptabase-mcp 登入。

Cursor

在 ~/.cursor/mcp.json 加入以下伺服器設定（檔案不存在時請先建立）：

{
    "mcpServers": {
        "heptabase-mcp": {
            "url": "https://api.heptabase.com/mcp"
        }
    }
}

儲存檔案後重新整理 Cursor，並完成登入。

Antigravity CLI

在 ~/.gemini/antigravity-cli/mcp_config.json，或工作區的 .agents/mcp_config.json 加入以下伺服器設定：

{
    "mcpServers": {
        "heptabase-mcp": {
            "serverUrl": "https://api.heptabase.com/mcp"
        }
    }
}

Antigravity CLI 透過 serverUrl 直接連線，不需要 mcp-remote。如果在開始登入前就顯示 Unauthorized，請聯絡我們，並附上 Antigravity CLI 版本與錯誤畫面截圖。

其他服務

任何支援遠端 MCP 伺服器的 AI 服務都可以連接 Heptabase。

在該服務中找到新增 MCP 伺服器的地方。
輸入 https://api.heptabase.com/mcp。
跳轉到 Heptabase 後登入並授權連線。
回到原本的服務，即完成連接。

試試第一個任務

不需要記住工具名稱。描述你想做的事，AI 助理會自己選擇工具。

任務	範例提示
搜尋並摘要	找出我關於再生能源的筆記，整理最相關的幾張。
寫進日誌	把這段摘要加到今天的日誌。
存下資料來源	把這篇論文存成 PDF 卡片，並整理第一節的重點：https://arxiv.org/pdf/1706.03762
整理白板	把「論文」白板上的卡片依主題分成幾個區塊。
處理 Inbox	看過我的 Inbox，替每張卡片建議適合的白板或標籤。

權限

AI 助理能做哪些事，取決於連接時你授予的權限。唯讀連線可以搜尋和閱讀，但無法做任何變更。若要讓 AI 助理修改內容，請重新連接並授予寫入權限。

工具參考

若想精確指定 AI 助理的做法，可以直接點名工具，例如：「用 search_by_keyword 找出包含這段文字的筆記。」

查看完整的 MCP 工具參考 →