The current MCP tool set can list, search, read, create, edit, and display content in your Heptabase space. Interactive card display requires a client that supports MCP Apps.

Browse cards, tags, and whiteboards

Cards · list_cards

Lists cards without reading their content. You can filter by card type, whiteboard or tag membership, timestamps, or known IDs, and include lightweight metadata such as tags, whiteboards, and timestamps.

Highlights are excluded by default. To list them, ask the assistant to include highlightElement in objectTypes. Results are paginated: the default is 20 cards per call, with a maximum of 100. Ask the assistant to continue through every page when you need a complete list.

Tags · list_tags

Lists tags with their hierarchy and card counts. Use it to discover a tag ID before filtering cards or reading a tag database.

Whiteboards · list_whiteboards

Lists the whiteboard hierarchy with lightweight object counts and pagination.

Search your Heptabase space

Keywords · search_by_keyword

Searches titles and supported text content using exact keywords or short phrases. PDF, video, and audio cards are searched by title only. Use a read tool when you need complete content.

Meaning · search_by_semantic

Searches by meaning using a natural-language query. This is useful when relevant notes may use different wording. Semantic search does not search tags or whiteboards.

Within an object · search_object_content

Searches literal or regular-expression text inside one known object. It returns matching excerpts with line numbers and can search stored parsed content for PDF cards.

Read content and structure

Card content · read_object

Reads a specific object after another tool returns its ID. Long text can be read in parts. For a PDF card, this tool returns metadata; use read_pdf for page content.

Whiteboard · read_whiteboard

Reads either a whiteboard’s structure or the content of the objects placed on it.

Journal range · read_journal_range

Reads existing daily journal entries in an inclusive date range, oldest first. Each call can cover at most 92 days.

Database · read_database

Reads a tag database’s property schema, views, filters, sorts, select options, and relation targets.

PDF pages · read_pdf

Reads an inclusive, 1-indexed page range from a parsed PDF card. The PDF must already be supported and successfully parsed.

Images · read_image

Reads an image referenced by read_object using the image reference’s file and source-object information.

PDF highlight source anchors are not currently included in MCP read results. MCP does not provide the source PDF ID, page number, highlighted region coordinates/rects, or an equivalent precise deep link for an individual highlight. There is also no whiteboard-scoped export containing those anchors. A full-account export is currently required if you need to reconstruct them.

Display cards and read reference pages

Display cards · render_cards

Displays selected Heptabase cards in an interactive view in compatible MCP Apps clients, such as ChatGPT or the Codex app. It supports notes, journals, PDF, video, audio, image, and web cards, as well as highlights. Each call accepts up to 20 card references; duplicate references are displayed once.

Try asking: “Find my notes about renewable energy, summarize the most relevant ones, and show me those cards.” You can also ask to see a card after the assistant creates or edits it. In a plain-text or terminal client, the assistant should present the results as text instead.

Reference pages · read_system_manual_page

Reads Heptabase MCP reference pages for core concepts, rich-text syntax, and database properties.

Create and edit content

Create content · create_object

Creates a new note card, or creates a journal entry when no journal exists for that date.

Append to journal · append_to_journal

Appends content to an existing journal entry, or creates the journal entry if it does not exist.

Edit content · edit_object_content

Finds and replaces exact text in a note card or journal entry.

Set properties · edit_card_properties

Updates property values for a card in an existing tag database.

Add to a tag · update_database_card_membership

Adds existing cards to a tag database.

Place on a board · place_whiteboard_objects

Automatically places existing note cards, journals, PDF, image, video, audio, and web cards on a whiteboard. It does not provide precise positioning, moving, resizing, or editing of sections, text elements, mind maps, or connections. For those layout operations, use the Heptabase app or the Heptabase CLI.

Important: Heptabase MCP can currently create note cards and journal entries, but it cannot upload files or create new image cards. To use an image, upload or paste it into Heptabase first. MCP can then find, read, or place the existing image card on a whiteboard. If you only need a reference, create a note card containing the image URL.

Typical workflow

A typical workflow combines several tools:

Browse: use list_cards, list_tags, or list_whiteboards to discover what exists.
Search: use search_by_keyword for exact wording, search_by_semantic for related ideas, or search_object_content inside a known object.
Read: use the relevant read tool to retrieve full content, whiteboard structure, journal ranges, database configuration, PDF pages, or images.
Create or edit: create cards, append to journals, edit card content and properties, add cards to tag databases, or place existing objects on whiteboards.
Display: in a compatible MCP Apps client, use render_cards to show the cards selected for the user after finding or updating them.

Heptabase MCP tool reference