Skip to main content

Heptabase MCP tool reference

Browse MCP tools by task, and see which ones need Heptabase open.

This page lists every Heptabase MCP tool, grouped by task. You do not need to name tools in your requests; your assistant picks them. To connect an assistant, see Heptabase MCP.

​

Tools marked Needs Heptabase open run in the Heptabase app. Keep the desktop app or the web app open and signed in to the same account. When you connect through ChatGPT or Claude, the assistant can open Heptabase inside the chat instead. All other tools work without the app.

​

​

​

Browse and search

  • list_cards: Lists cards by type, tag, whiteboard, or time, without reading their content.

  • list_tags: Lists your tags with their hierarchy and card counts.

  • list_whiteboards: Lists your whiteboards and their hierarchy.

  • search_by_keyword: Finds content by exact words or short phrases. PDF, video, and audio cards are matched by title only.

  • search_by_semantic: Finds content by meaning, even when it uses different words.

  • search_object_content: Searches for text inside one card, journal, or parsed PDF.

​

​

Read

  • read_object: Reads a card, journal, or other object. Long content can be read in parts.

  • read_journal_range: Reads your journals in a date range, up to 185 days per call.

  • read_whiteboard: Reads a whiteboard's structure, or the content of the objects on it.

  • read_pdf: Reads pages of a parsed PDF card.

  • read_image: Reads an image, including images parsed from PDFs.

  • read_card_highlights: Reads the highlights on a note card or PDF card, with their notes.

  • read_backlinks: Finds the cards, journals, and whiteboards that link to, mention, or place an object. Needs Heptabase open.

  • read_database: Reads a tag database's properties, select options, and views.

  • query_database: Finds cards in a tag database with filters and sorts. Needs Heptabase open.

  • get_file_download_url: Downloads an original PDF, image, audio, video, or attachment.

​

​

Write notes and journals

  • create_object: Creates a note card, or a journal for a date that has none.

  • edit_note_card_content: Edits part of a note card without rewriting it: replaces exact text, adds content at the end, or rewrites the whole card. The changes in one call are saved together, or none are.

  • edit_journal_content: Edits a journal the same way, and creates the journal if that date has none.

All three can add images, videos, audio, and attachments, from files in Heptabase or from links.

​

​

​

Save files and links as cards

  • import_file_from_url: Imports a file from a public link, up to 50 MB.

  • get_file_upload_url, import_file_from_upload: Upload a file from your computer, up to 2,000 MB. The assistant needs to be able to run commands, as in Codex or Claude Code.

  • create_pdf_card_from_file, create_image_card_from_file, create_audio_card_from_file, create_video_card_from_file: Create a card from an imported file.

  • parse_pdf: Parses a PDF card so its pages can be read. Long PDFs can take a few minutes.

  • create_web_card_from_url: Saves a web page as a web card.

  • create_video_card_from_url: Saves a YouTube video as a video card, with its captions as the transcript.

Saving a link that already has a card reuses that card instead of creating a duplicate, and restores it if it is in the trash.

​

​

​

Organize cards and tags

  • edit_card_properties: Sets property values on cards in a tag database.

  • update_database_card_membership: Adds cards to a tag database, or removes them from it without deleting the cards. Removing needs Heptabase open.

  • create_database: Creates a tag database.

  • edit_database: Renames a tag database and edits its properties, select options, and views. Needs Heptabase open.

  • create_tag_group: Creates a tag group in the Tags sidebar.

  • move_tags: Moves tags under another tag, into a tag group, or to the top level.

  • trash_cards: Moves cards to the trash. Trashed cards stay on their whiteboards until they are removed.

  • restore_cards: Restores cards from the trash, back where they were.

  • rename_object: Renames a whiteboard, section, or PDF, web, image, video, or audio card. Needs Heptabase open.

​

​

Process your Inbox

  • list_inbox_items: Lists what is in your Inbox: cards and messages you added, mentions, replies, quotes, and invites.

  • add_cards_to_inbox: Adds cards to your Inbox, optionally with a date to remind you.

  • update_inbox_items: Marks items done, read, or unread, or sets or clears a reminder date.

  • remove_inbox_items: Removes cards and messages you added from the Inbox, without deleting them. Mentions, replies, quotes, and invites can only be marked done.

When the assistant picks which items to change or remove, it lists them and waits for you to confirm first.

​

​

Work on whiteboards

Every tool in this section needs Heptabase open, except place_whiteboard_objects. Without the app, place_whiteboard_objects can only place cards to the right of existing content.

  • create_whiteboard: Creates a whiteboard or a sub-whiteboard.

  • move_whiteboard: Moves a whiteboard to another place in the hierarchy.

  • create_whiteboard_shortcut: Shows a whiteboard on another whiteboard as a shortcut.

  • place_whiteboard_objects: Places existing cards and journals on a whiteboard.

  • move_whiteboard_objects: Moves objects within a whiteboard.

  • move_whiteboard_objects_across_whiteboards: Moves objects to another whiteboard, keeping their layout.

  • arrange_whiteboard_objects: Arranges objects in a row, column, or grid.

  • align_whiteboard_objects: Aligns objects by an edge or center.

  • resize_whiteboard_objects: Resizes, folds, or expands objects.

  • update_whiteboard_objects_color: Changes the color of objects and connections.

  • remove_whiteboard_objects: Removes objects from a whiteboard without deleting the cards.

  • create_section: Creates a section around objects.

  • create_connections: Connects objects, with or without labels.

  • update_connection: Changes a connection's route or color.

  • create_mind_map: Creates a mind map from text, cards, and highlights.

  • update_mind_map: Adds, edits, moves, or deletes mind map nodes, and changes its layout.

  • read_whiteboard_layout: Reads the position and size of every object.

  • lint_whiteboard: Checks a whiteboard for overlapping objects and crossing connections.

  • screenshot_whiteboard: Takes a simplified picture of a whiteboard so the assistant can check its layout.

​

​

Show results in the chat

  • render_cards: Shows cards in an interactive view in ChatGPT, Claude, and Codex.

  • open_heptabase: Opens a whiteboard inside the chat, where you can edit it and watch the assistant's changes.

  • navigate_heptabase: Switches the whiteboard open in the chat, or opens a card beside it.

  • read_heptabase_view: Checks which whiteboard and card you have open in the chat.

open_heptabase and the two tools after it are available only when the connection was set up in ChatGPT or Claude, such as through the official plugin. Codex and Claude Code in the Claude desktop app can open the whiteboard too when they use that connection. Connections that Codex or Claude Code set up on their own, and Codex CLI or Claude Code in a terminal or an IDE, cannot open Heptabase in the chat.

​

​

​

Follow your Space Instructions

  • read_space_instructions: Reads your Space Instructions, the standing rules you set for how AI works in your space. The assistant reads them before it starts working and follows them.

  • set_space_instructions: Makes an existing note card your Space Instructions. To add a rule later, the assistant edits that card.

​

​

​

Reference pages

read_system_manual_page gives the assistant Heptabase's own guide to these tools: core concepts, Space Instructions, organizing your knowledge base, processing the Inbox, saving external sources, the formatting syntax for notes, tag database property values, and how to lay out whiteboards and mind maps. Assistants read it on their own when they need it.

Did this answer your question?