@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

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