@heptabase/mcp

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

特征

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

快速入门

安装和设置

克隆并安装：
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 社区打造

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

模型上下文协议服务允许 AI 助手从 Heptabase 备份中搜索、检索、分析和导出数据。

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