Heptabase

You run a Model Context Protocol (MCP) server to access and manage Heptabase backup data locally, enabling you to search whiteboards and cards, generate summaries, and export content in multiple formats. This server keeps backup data on your machine, supports fast access through smart caching, and integrates with your MCP client for seamless AI-assisted workflows.

How to use

Start by ensuring your MCP client is configured to connect to the local MCP server that handles Heptabase backups. You can operate tools to locate backups, search whiteboards and cards, retrieve full whiteboard data, and export results to Markdown, JSON, or HTML. Use the tooling to analyze relationships between cards, summarize whiteboards, and troubleshoot as needed. All interactions are performed locally, with backups remaining on your machine for privacy and security.

How to install

# Prerequisites
- Node.js 18+ installed on your system

# 1. Clone the MCP server repository
git clone <repository-url>
cd heptabase-mcp

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Start the server (development/start command may vary by setup)
npm start

Configuration and usage notes

The MCP server supports a privacy-safe configuration setup. You can place example configuration templates in your project and create personal, gitignored config files for sensitive data. The following environment variables are commonly used to tailor the local runtime to your Heptabase backup directory.

# Claude Desktop or local MCP client configuration (stdio startup)
{
  "mcpServers": {
    "heptabase": {
      "command": "node",
      "args": ["/path/to/your/heptabase-mcp/dist/index.js"],
      "env": {
        "HEPTABASE_BACKUP_PATH": "/path/to/your/heptabase/backups",
        "HEPTABASE_AUTO_EXTRACT": "true",
        "HEPTABASE_WATCH_DIRECTORY": "true"
      }
    }
  }
}

What you can do with the tools

Use the available tools to manage backups, search content, fetch complete whiteboards, and export or summarize data. Typical actions include configuring the backup path, listing backups, loading a backup, searching whiteboards or cards, retrieving whiteboard or card content, exporting to formats, generating summaries, analyzing graph relationships, and debugging the system.

Available tools

configureBackupPath

Set the backup directory to use for MCP operations.

listBackups

List available backups for selection.

loadBackup

Load a specific backup into the MCP session.

searchWhiteboards

Search whiteboards by name or content.

searchCards

Search cards across all whiteboards.

getWhiteboard

Retrieve complete whiteboard data, optionally including cards and connections.

getCard

Get card content in multiple display formats.

getCardContent

Retrieve card content as a resource, useful for large payloads.

getCardsByArea

Find cards by their position on a whiteboard.

exportWhiteboard

Export a whiteboard to Markdown, JSON, or HTML.

summarizeWhiteboard

Generate AI-powered summaries of whiteboards.

analyzeGraph

Analyze relationships and connections between cards.

compareBackups

Compare different backup versions to identify changes.

debugInfo

Provide system status and diagnostics for troubleshooting.