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

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.

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 enables 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
WebSearch-MCP
mnhlt
A
security
F
license
A
quality
A Model Context Protocol server that enables AI assistants to perform real-time web searches, retrieving up-to-date information from the internet via a Crawler API.
Last updated -
1
44
8
JavaScript

View all related MCP servers