Heptabase MCP

@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

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

A Model Context Protocol service that allows AI assistants to search, retrieve, analyze, and export data from Heptabase backups.

Related Resources

Reddit Discussion about this server

Related MCP Servers

MCP Personal Assistant Agent
zhangzhongnan928
-
security
F
license
-
quality
A versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.
Last updated -
2
Python
MCP Kibela
kj455
A
security
A
license
A
quality
A Model Context Protocol server that enables AI assistants to search and access information stored in Kibela, supporting note search, retrieval, creation and updating.
Last updated -
6
107
9
TypeScript
MIT License
Tiny TODO MCP
tkc
-
security
F
license
-
quality
A Model Context Protocol server that provides persistent task management capabilities for AI assistants, allowing them to create, update, and track tasks beyond their usual context limitations.
Last updated -
1
TypeScript
Amadeus MCP Server
privilegemendes
A
security
F
license
A
quality
A Model Context Protocol server that connects to Amadeus API, enabling AI assistants to search flights, analyze prices, find best travel deals, and plan multi-city trips.
Last updated -
294
TypeScript

View all related MCP servers