@heptabase/mcp

用于与 Heptabase 备份数据交互的模型上下文协议 (MCP) 服务。该服务允许像 Claude 这样的 AI 助手搜索、检索、分析和导出 Heptabase 白板和卡片。

特征

🔍 搜索白板和卡片
📁 自动备份文件管理
📄 导出为多种格式（Markdown、JSON、Mermaid）
🔗 分析卡片关系
📊 生成白板摘要
⚡ 智能缓存以提高性能

Related MCP server: Supabase MCP Server

快速入门

安装和设置

克隆并安装：
git clone <repository-url> cd heptabase-mcp npm install
使用环境变量进行配置：
cp .env.example .env # Edit .env with your actual paths
构建项目：
npm run build
本地测试（可选）：
npm start

与 Claude Desktop 一起使用

配置 Claude Desktop 以使用您的本地构建：

编辑您的 Claude Desktop 配置文件：

macOS ： ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows ： %APPDATA%\Claude\claude_desktop_config.json
Linux ： ~/.config/Claude/claude_desktop_config.json

添加此配置：

{ "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" } } } }

重要的：

将/path/to/node替换为您的 Node.js 路径（使用which node查找）
将/path/to/your/heptabase-mcp替换为您的实际项目路径
将HEPTABASE_BACKUP_PATH设置为您的 Heptabase 备份目录

有关详细的设置说明，请参阅QUICK_START.md 。

配置

该项目采用隐私安全配置系统：

示例文件（适用于 git）： claude-config-example.json 、 .env.example
个人文件（忽略）： claude-config-*personal*.json 、 .env

有关详细配置说明，请参阅CONFIG.md 。

基本用法

// 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" } });

可用工具

备份管理

configureBackupPath - 设置备份目录
listBackups列出可用的备份
loadBackup - 加载特定备份

搜索行动

searchWhiteboards - 按名称或内容搜索白板
searchCards - 在所有白板上搜索卡片

数据检索

getWhiteboard - 获取完整的白板数据
getCard - 获取多种格式的卡片内容
getCardContent - 获取卡片内容作为资源（绕过大小限制）
getCardsByArea - 根据白板上的位置查找卡片

导出函数

exportWhiteboard - 导出为 Markdown、JSON、HTML 格式
summarizeWhiteboard - 生成人工智能摘要

分析工具

analyzeGraph - 分析卡片关系和连接
compareBackups - 比较不同的备份版本

调试工具

debugInfo - 获取系统状态和诊断

发展

项目结构

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

测试

# 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

建筑

# Build for production npm run build # Development mode with auto-reload npm run dev # Type checking only npm run type-check

文档

📚 完整规范- 详细的 API 和架构
🚀 快速入门指南- 快速启动并运行
⚙️ 配置指南- 安全配置实践
📖 Claude 桌面设置- 本地开发设置

隐私和安全

该项目遵循隐私设计原则：

✅ 个人路径永远不会提交给 git
✅ 备份数据保留在您的本地机器上
✅ 配置模板使用安全占位符
✅ Gitignore 保护敏感文件

要求

Node.js 18+
启用备份导出的Heptabase
Claude Desktop （用于 MCP 集成）

故障排除

常见问题

“未找到备份” - 检查您的HEPTABASE_BACKUP_PATH是否指向正确的目录
“未找到命令” - 确保 Node.js 已安装且路径正确
Claude 看不到工具- 配置更改后完全重启 Claude Desktop
构建错误- 使用前运行npm install和npm run build

调试模式

使用debugInfo工具检查系统状态：

await mcpClient.callTool({ name: "debugInfo" });

贡献

欢迎投稿！请：

分叉存储库
创建功能分支
进行更改
添加新功能测试
确保所有测试通过
提交拉取请求

有关架构详细信息，请参阅SPECIFICATION.md 。

执照

MIT 许可证 - 详情请参阅LICENSE文件。

支持

🐛错误报告： GitHub Issues
💬问题： GitHub 讨论
📧安全问题：请私下报告

用❤️为 Heptabase 社区打造

Heptabase MCP