What can you do with this server?

The Heptabase MCP server is a Model Context Protocol service for interacting with Heptabase backup data, allowing you to: * **Manage backups**: Configure paths, list available backups, and load specific ones * **Search**: Find whiteboards and cards using keywords, tags, spaces, date ranges, or content types * **Retrieve data**: Access detailed whiteboard and card information, including content and relationships * **Export**: Convert whiteboards to Markdown, JSON, or HTML formats * **Analyze**: Examine card relationships, generate summaries, calculate graph metrics, and compare backups * **Debug**: Access troubleshooting information about the server * **Spatial queries**: Find cards within specified areas on whiteboards

Which integrations are available for this server?

Allows exporting Heptabase whiteboards and cards to [Markdown](/mcp/servers/integrations/markdown) format Supports exporting Heptabase whiteboards to [Mermaid](/mcp/servers/integrations/mermaid) diagrams for visual representation

@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

Related MCP server: Supabase MCP Server

Quick Start

Installation and Setup

Clone and install:
git clone <repository-url> cd heptabase-mcp npm install
Configure using environment variables:
cp .env.example .env # Edit .env with your actual paths
Build the project:
npm run build
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:

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
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

Heptabase MCP