What can you do with this server?

The Heptabase MCP server enables AI assistants to interact with Heptabase backup data through multiple functions: * **Backup Management**: Configure paths, list available backups, and load specific backups * **Search Operations**: Find whiteboards and cards using queries, filters, tags, and date ranges * **Data Retrieval**: Access whiteboard and card data, including cards within specific areas * **Export Functions**: Export content to Markdown, JSON, and HTML formats * **Analysis Tools**: Analyze card relationships, compare backups, and evaluate graph metrics * **Summaries**: Generate whiteboard summaries * **Debugging**: Access server state information for troubleshooting

Which integrations are available for this server?

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

@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

Using with Claude Desktop (Recommended)

The easiest way to use this MCP service is with Claude Desktop via npx:

{ "mcpServers": { "heptabase": { "command": "npx", "args": ["@heptabase/mcp"], "env": { "HEPTABASE_BACKUP_PATH": "/path/to/your/heptabase/backups", "HEPTABASE_AUTO_EXTRACT": "true", "HEPTABASE_WATCH_DIRECTORY": "true" } } } }

See CLAUDE_DESKTOP_NPX.md for detailed setup instructions.

Local Development

Install dependencies:
npm install
Configure using environment variables. Create a .env file:
HEPTABASE_BACKUP_PATH=/path/to/your/heptabase/backups HEPTABASE_AUTO_EXTRACT=true HEPTABASE_WATCH_DIRECTORY=true
Start the MCP server:
npm start

Basic Usage

// Configure backup path await mcpClient.callTool({ name: "configureBackupPath", parameters: { path: "/Users/stanley/Documents/Heptabase-auto-backup" } }); // List available backups const { backups } = await mcpClient.callTool({ name: "listBackups" }); // Search for whiteboards const { whiteboards } = await mcpClient.callTool({ name: "searchWhiteboards", parameters: { query: "Project Planning" } });

Available Tools

Backup Management

configureBackupPath - Set backup directory
listBackups - List available backups
loadBackup - Load a specific backup

Search Operations

searchWhiteboards - Search whiteboards
searchCards - Search cards

Data Retrieval

getWhiteboard - Get whiteboard data
getCard - Get card data
getCardsByArea - Get cards by position

Export Functions

exportWhiteboard - Export to various formats
summarizeWhiteboard - Generate summaries

Analysis Tools

analyzeGraph - Analyze relationships
compareBackups - Compare versions

Development

Project Structure

heptabase-mcp/ ├── src/ │ ├── index.ts # MCP server │ ├── config/ # Configuration │ ├── services/ # Core services │ ├── tools/ # MCP tools │ └── types/ # TypeScript types ├── tests/ # Test files ├── package.json └── tsconfig.json

Testing

npm test

Building

npm run build

Documentation

For detailed documentation, see SPECIFICATION.md.

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Support

For issues and feature requests, please use the GitHub issue tracker.

One-click Deploy

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Reddit Discussion

Related Servers

Tools

View all tools

Heptabase MCP