헵타베이스 MCP

@헵타베이스/mcp

Heptabase 백업 데이터와 상호 작용하기 위한 모델 컨텍스트 프로토콜(MCP) 서비스입니다. 이 서비스를 통해 Claude와 같은 AI 비서가 Heptabase 화이트보드와 카드를 검색, 불러오기, 분석 및 내보낼 수 있습니다.

특징

🔍 화이트보드와 카드 검색
📁 자동 백업 파일 관리
📄 다양한 포맷(Markdown, JSON, Mermaid)으로 내보내기
🔗 카드 관계 분석
📊 화이트보드 요약 생성
⚡ 성능을 위한 스마트 캐싱

빠른 시작

설치 및 설정

복제하고 설치하세요:지엑스피1
환경 변수를 사용하여 구성:
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
윈도우 : %APPDATA%\Claude\claude_desktop_config.json
리눅스 : ~/.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 Desktop 설정 - 로컬 개발 설정

개인정보 보호 및 보안

이 프로젝트는 개인정보 보호 원칙을 따릅니다.

✅ 개인 경로는 git에 커밋되지 않습니다.
✅ 백업 데이터는 컴퓨터에 로컬로 저장됩니다.
✅ 구성 템플릿은 안전한 플레이스홀더를 사용합니다.
✅ Gitignore는 민감한 파일을 보호합니다

요구 사항

노드.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 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.

지원하다

🐛 버그 리포트 : GitHub 이슈
💬 질문 : 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