ヘプタベースMCP

@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
個人ファイル（gitignored）： 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 - AIを活用した要約を生成

分析ツール

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コミュニティのために❤️を込めて作りました

Install 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

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
Amadeus MCP Server
privilegemendes
A
security
F
license
A
quality
A Model Context Protocol server that connects to Amadeus API, enabling AI assistants to search flights, analyze prices, find best travel deals, and plan multi-city trips.
Last updated -
294
TypeScript

View all related MCP servers

Heptabase MCP