Use the official Heptabase plugin to work with your cards, journals, whiteboards, and tag databases from Claude or Claude Code. The plugin connects to your Heptabase account online, so you do not need to install the Heptabase CLI or keep the Heptabase desktop app running.
Install and connect Heptabase
Claude
To connect Heptabase in your personal workspace:
Open Claude on the web or in the desktop app.
Open Customize → Plugins → Discover.
Search for Heptabase, select the plugin, and click Add.
Connect your Heptabase account. When prompted, sign in, review the requested permissions, and approve the connection.
Start a new chat and ask Claude to use Heptabase.
If you use a Team or Enterprise workspace and cannot find Heptabase, check with your workspace owner about plugin availability.
The interface may change as Claude is updated. See Claude's plugin guide for the latest instructions.
Claude Code
Plugins installed in Claude sync to Claude Code when you sign in with the same Claude account. Start a new session after installation. If prompted, run /reload-plugins to activate the plugin.
You can also install it directly from the official Heptabase plugin repository:
Open Claude Code in your terminal.
Enter this command to add the Heptabase marketplace:
/plugin marketplace add heptameta/heptabase-agent-plugins
Install the plugin:
/plugin install heptabase@heptabase-agent-plugins
Choose Install for you to use the plugin in all your projects on this computer.
Start a new session, then enter
/mcpand select the Heptabase connection to authenticate.Complete the Heptabase sign-in and authorization steps in your browser, then return to Claude Code.
See Claude Code's MCP guide for more about authentication.
Get started
Tell Claude what you want to do in Heptabase. For example:
“Find my Heptabase cards about renewable energy and summarize the main ideas.”
“Save the key takeaways from this discussion as a new card in Heptabase.”
“Append this summary to today's journal.”
“Update the conclusion in my ‘Research plan’ card based on what we just discussed.”
“Add this card to my existing ‘Reading’ tag and place it on my ‘Research’ whiteboard.”
In Claude, you can also ask to see the cards it finds, creates, or edits. Select Open in Heptabase in a card preview to continue working in Heptabase. Claude Code's terminal shows results as text instead of interactive card previews.
Supported content and actions
The Heptabase plugin can:
Search and read cards, journals, whiteboards, and tag databases.
Read images and successfully parsed PDFs.
Create and edit note cards and journals.
Add cards to existing tags and update existing property values.
Place existing cards and other supported content on a whiteboard.
Current limitations:
It cannot create new tags, property columns, or property options.
It cannot upload files or create new image cards.
Objects placed on a whiteboard are arranged automatically. The plugin cannot set exact positions or sizes, or edit connections.
See the Heptabase MCP tool reference for the full list of supported actions and limitations.
Permissions and connection issues
The available actions depend on the permissions granted when you connect Heptabase. A read-only connection can search and read content, but it cannot create or edit content. Reconnect with write access if you want Claude to make changes.
If the plugin is not working as expected:
Confirm that you connected the intended Heptabase account.
Start a new chat or Claude Code session after installation.
If Claude is not using Heptabase, mention Heptabase in your request.
In Claude Code, enter
/mcpto check the connection and authenticate if needed.If the connection has expired, reconnect it.
If the issue continues, contact Heptabase support with the app you are using and the error message.
Other connection methods
For manual setup with another compatible AI service, see Heptabase MCP.
For more control over whiteboard layout, use the Heptabase CLI with the Heptabase desktop app running.