@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

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

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

Metabase MCP Server
sazboxai
-
security
F
license
-
quality
A Model Control Protocol server that enables AI assistants to interact with Metabase databases, allowing models to explore database schemas, retrieve metadata, visualize relationships, and execute actions.
Last updated -
5
Supabase MCP Server
ninad7007
-
security
A
license
-
quality
A Model Context Protocol server that enables AI tools to interact with Supabase databases, providing tools for reading, creating, updating, and deleting records in Supabase tables.
Last updated -
MIT License
Heptabase MCP
LarryStanley
A
security
A
license
A
quality
A Model Context Protocol service that enables AI assistants to search, retrieve, analyze, and export data from Heptabase backups.
Last updated -
14
9
MIT License
MCP SQL Server
ryudg
-
security
A
license
-
quality
A Model Context Protocol server that provides AI assistants with comprehensive access to SQL databases, enabling schema inspection, query execution, and database operations with enterprise-grade security.
Last updated -
1
2
MIT License

View all related MCP servers

Heptabase MCP