@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:
- Test locally (optional):
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"
}
});
Backup Management
configureBackupPath - Set backup directorylistBackups - List available backupsloadBackup - Load a specific backup
Search Operations
searchWhiteboards - Search whiteboards by name or contentsearchCards - Search cards across all whiteboards
Data Retrieval
getWhiteboard - Get complete whiteboard datagetCard - Get card content in multiple formatsgetCardContent - Get card content as resource (bypasses size limits)getCardsByArea - Find cards by position on whiteboard
Export Functions
exportWhiteboard - Export to Markdown, JSON, HTML formatssummarizeWhiteboard - Generate AI-powered summaries
analyzeGraph - Analyze card relationships and connectionscompareBackups - Compare different backup versions
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
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
Made with ❤️ for the Heptabase community