Heptabase MCP and the Heptabase CLI both let you use Heptabase from other AI tools: search, read, write, and organize your cards, journals, and whiteboards. They can do most of the same things. The main difference is how they connect.
Use MCP with chat apps such as ChatGPT and Claude, or any other AI tool that supports MCP. The official Heptabase plugin connects through MCP: see Use Heptabase with ChatGPT and Codex or Use Heptabase with Claude and Claude Code.
Use the CLI when your AI tool works in a terminal on the computer where the Heptabase desktop app runs. It is the better fit when you want to read AI Tutor courses, or have AI work with files on your computer directly.
The basics
MCP | CLI | |
How it connects | Connects to your account through Heptabase's servers | Runs on your computer and connects through the Heptabase desktop app |
Setup | Install the official Heptabase plugin, or add the MCP server URL to your AI tool, then sign in to Heptabase and allow access | Turn on the CLI in the desktop app under Settings → AI Features → CLI, and install the Heptabase CLI skills |
Does Heptabase need to be open? | Not for most actions. Whiteboard editing and a few other actions need the desktop or web app open* | Yes, the desktop app must be running. heptabase start opens it for you |
Which AI tools | ChatGPT, Claude, Codex, Claude Code, Cursor, and other AI tools that support remote MCP servers | AI tools that can run commands on your computer, such as Claude Code and Codex |
Which space | Your own space. Spaces others share with you are out of reach | Same as MCP |
Files on your computer | No direct access. AI tools that can run commands can upload files to Heptabase, or fetch files with a download link | Imports files from your computer directly (up to 2,000 MB), and exports original files from Heptabase to a folder on your computer |
Subscription | Pro, Premium, or Premium+, or an active free trial | Same as MCP |
* For these actions, keep the Heptabase desktop app or the web app open and signed in to the same account. In ChatGPT, Claude, Codex, and Claude Code in the Claude desktop app, the AI can also open Heptabase right inside the chat to do them. The mobile app does not run these actions.
What each can do
✓ means supported, ✕ means not supported.
MCP | CLI | |
Search and read | ||
Search, and list cards and whiteboards | ✓ | ✓ |
Read cards, journals, whiteboards, and highlights | ✓ | ✓ |
Read backlinks | ✓* | ✓ |
Notes and journals | ||
Create and edit note cards and journals | ✓ | ✓ |
Read journals across a date range at once | ✓ | ✓ |
Trash and restore cards | ✓ | ✓ |
Rename whiteboards, sections, and media cards | ✓* | ✓ |
Whiteboards | ||
Place cards on a whiteboard | ✓ | ✓ |
Create and move whiteboards | ✓* | ✓ |
Move, arrange, align, resize, recolor, or remove objects | ✓* | ✓ |
Create sections, connections, and mind maps | ✓* | ✓ |
Check layouts and export schematic screenshots | ✓* | ✓ |
Tag databases | ||
List tags and read tag databases | ✓ | ✓ |
Create tag databases and tag groups, and move tags | ✓ | ✓ |
Edit and query tag databases | ✓* | ✓ |
Add tags to cards and set property values | ✓ | ✓ |
Remove tags from cards | ✓* | ✓ |
Files and media | ||
Save web pages and YouTube videos | ✓ | ✓ |
Create PDF, image, audio, and video cards from files | ✓¹ | ✓ |
Read PDFs and audio and video transcripts | ✓ | ✓ |
Look at images | ✓ | ✓² |
Get original files | Gets a download link | Exports to a folder on your computer |
Inbox and Space Instructions | ||
Read and organize your Inbox | ✓ | ✓ |
Read and set your Space Instructions | ✓ | ✓ |
Only one of them | ||
Show cards in the chat | ✓³ | ✕ |
Open and edit a whiteboard inside the chat | ✓⁴ | ✕ |
Read AI Tutor courses, lessons, and chat history | ✕ | ✓ |
* Needs the Heptabase desktop or web app open, or Heptabase opened inside the chat, as described above.
¹ Files on the web can be imported by URL. Files on your computer must be uploaded by an AI tool that can run commands, such as Claude Code or Codex; in other AI tools, add the file to Heptabase first.
² The CLI exports the image to your computer first, and your AI tool opens it with its own tools.
³ Shown only in AI tools that support it. Other tools reply in text instead.
⁴ In ChatGPT, Claude, Codex, and Claude Code in the Claude desktop app, when you connect through the Heptabase plugin or connector added in those apps.
How they differ from the AI Agent in Heptabase
Heptabase also has a built-in AI Agent. Here is how it differs from MCP and the CLI:
Where it works: the AI Agent runs inside Heptabase. It knows which card or whiteboard you are viewing and which objects you have selected, and it works in the space you are in, including spaces others share with you. MCP and the CLI connect from other AI tools and work only in your own space.
Usage: the AI Agent uses Heptabase AI credits, or your own API key or Codex sign-in. With MCP or the CLI, the model in your AI tool answers you under that tool's plan, and no Heptabase AI credits are used.
AI Tutor: courses run only inside Heptabase.
To learn what the AI Agent reads, see What Space content can the AI Agent access?. For AI credits, see Plans and pricing.