What is Heptabase Mcp

heptabase-mcp is a Model Context Protocol (MCP) service designed for interacting with Heptabase backup data, enabling AI assistants to search, retrieve, analyze, and export data from Heptabase whiteboards and cards.

Use cases

Use cases for heptabase-mcp include project planning, collaborative brainstorming sessions, data analysis for educational purposes, and generating reports from visual data for presentations.

How to use

To use heptabase-mcp, you can start with Claude Desktop using the command ‘npx @heptabase/mcp’. For local development, install dependencies, configure environment variables in a .env file, and start the MCP server using ‘npm start’.

Key features

Key features of heptabase-mcp include searching whiteboards and cards, automatic backup file management, exporting to multiple formats (Markdown, JSON, Mermaid), analyzing card relationships, generating whiteboard summaries, and smart caching for performance.

Where to use

heptabase-mcp can be used in various fields including project management, educational tools, and any application that requires efficient management and analysis of visual data represented in whiteboards and cards.

@heptabase/mcp

A Model Context Protocol (MCP) service for interacting with Heptabase backup data. This service allows AI assistants like Claude to search, retrieve, analyze, and export Heptabase whiteboards and cards.

Features

• 🔍 Search whiteboards and cards
• 📁 Automatic backup file management
• 📄 Export to multiple formats (Markdown, JSON, Mermaid)
• 🔗 Analyze card relationships
• 📊 Generate whiteboard summaries
• ⚡ Smart caching for performance

Quick Start

Installation and Setup

1. Clone and install:

   git clone <repository-url>
   cd heptabase-mcp
   npm install
   

2. Configure using environment variables:

   cp .env.example .env
   # Edit .env with your actual paths
   

3. Build the project:

   npm run build
   

4. Test locally (optional):

   npm start
   

Using with Claude Desktop

Configure Claude Desktop to use your local build:

Edit your Claude Desktop config file:

• macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "heptabase": {
      "command": "/path/to/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"
      }
    }
  }
}

Important:

• Replace /path/to/node with your Node.js path (find with which node)
• Replace /path/to/your/heptabase-mcp with your actual project path
• Set HEPTABASE_BACKUP_PATH to your Heptabase backup directory

See QUICK_START.md for detailed setup instructions.

Configuration

This project uses a privacy-safe configuration system:

• Example files (safe for git): claude-config-example.json, .env.example
• Personal files (gitignored): claude-config-*personal*.json, .env

See CONFIG.md for detailed configuration instructions.

Basic Usage

// Configure backup path
await mcpClient.callTool({
  name: "configureBackupPath",
  parameters: {
    path: "/path/to/your/heptabase/backups"
  }
});

// List available backups
const backups = await mcpClient.callTool({
  name: "listBackups"
});

// Search for whiteboards
const whiteboards = await mcpClient.callTool({
  name: "searchWhiteboards",
  parameters: {
    query: "Project Planning"
  }
});

// Get full whiteboard content
const whiteboard = await mcpClient.callTool({
  name: "getWhiteboard",
  parameters: {
    whiteboardId: "your-whiteboard-id",
    includeCards: true,
    includeConnections: true
  }
});

// Export to markdown
const markdown = await mcpClient.callTool({
  name: "exportWhiteboard",
  parameters: {
    whiteboardId: "your-whiteboard-id",
    format: "markdown"
  }
});

Available Tools

Backup Management

• configureBackupPath - Set backup directory
• listBackups - List available backups
• loadBackup - Load a specific backup

Search Operations

• searchWhiteboards - Search whiteboards by name or content
• searchCards - Search cards across all whiteboards

Data Retrieval

• getWhiteboard - Get complete whiteboard data
• getCard - Get card content in multiple formats
• getCardContent - Get card content as resource (bypasses size limits)
• getCardsByArea - Find cards by position on whiteboard

Export Functions

• exportWhiteboard - Export to Markdown, JSON, HTML formats
• summarizeWhiteboard - Generate AI-powered summaries

Analysis Tools

• analyzeGraph - Analyze card relationships and connections
• compareBackups - Compare different backup versions

Debug Tools

• debugInfo - Get system status and diagnostics

Development

Project Structure

heptabase-mcp/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server implementation
│   ├── services/             # Core business logic
│   │   ├── BackupManager.ts  # Backup file management
│   │   └── HeptabaseDataService.ts # Data querying
│   ├── tools/                # MCP tool implementations
│   ├── types/                # TypeScript definitions
│   └── utils/                # Helper functions
├── tests/                    # Test suites
├── docs/                     # Documentation
└── config files              # Configuration templates

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

Building

# Build for production
npm run build

# Development mode with auto-reload
npm run dev

# Type checking only
npm run type-check

Documentation

• 📚 Complete Specification - Detailed API and architecture
• 🚀 Quick Start Guide - Get up and running fast
• ⚙️ Configuration Guide - Safe configuration practices
• 📖 Claude Desktop Setup - Local development setup

Privacy & Security

This project follows privacy-by-design principles:

• ✅ Personal paths are never committed to git
• ✅ Backup data stays local on your machine
• ✅ Configuration templates use safe placeholders
• ✅ Gitignore protects sensitive files

Requirements

• Node.js 18+
• Heptabase with backup exports enabled
• Claude Desktop (for MCP integration)

Troubleshooting

Common Issues

• “No backups found” - Check your HEPTABASE_BACKUP_PATH points to the correct directory
• “Command not found” - Ensure Node.js is installed and paths are correct
• Claude doesn’t see tools - Restart Claude Desktop completely after config changes
• Build errors - Run npm install and npm run build before using

Debug Mode

Use the debugInfo tool to check system status:

await mcpClient.callTool({ name: "debugInfo" });

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

See SPECIFICATION.md for architecture details.

License

MIT License - see LICENSE file for details.

Support

• 🐛 Bug reports: GitHub Issues
• 💬 Questions: GitHub Discussions
• 📧 Security issues: Please report privately

---

Made with ❤️ for the Heptabase community