kirby-k-0723/roam-mcp-server

Roam Research MCP Server

Roam Research와 Claude를 연결하는 고급 MCP(Model Context Protocol) 서버입니다.

주요 기능

✅ 강력한 검색 기능

• 페이지 제목 검색: 특정 페이지 이름으로 빠른 검색
• 전체 내용 검색: 페이지 제목과 블록 내용을 모두 검색
• 태그 기반 검색: 단일 태그 또는 여러 태그 조합으로 검색

✅ 스마트 자동 태그

• 키워드 인식: 내용을 분석하여 관련 태그 자동 추가
• 패턴 감지: URL, 코드, 날짜 등을 자동으로 인식하여 태그 추가
• 다국어 지원: 한국어와 영어 키워드 모두 지원

✅ 완전한 읽기/쓰기 지원

• 페이지 관리: 새 페이지 생성, 전체 내용 조회
• 블록 관리: 생성, 수정, 삭제 및 자동 태그 포함 생성
• Daily Note: 일일 노트에 자동 태그와 함께 블록 추가

✅ 다양한 접근 모드

• Stdio: 로컬 직접 연결 (기본)
• HTTP: 웹 기반 연결 (Railway 배포용)
• SSE: Server-Sent Events (실시간 업데이트)

설치 방법

1. 저장소 클론

git clone [저장소 URL]
cd roam-mcp-server

2. 의존성 설치

npm install

3. 환경 설정

cp .env.example .env

.env 파일을 열어 다음 값들을 설정하세요:

• ROAM_API_TOKEN: Roam Research API 토큰
• ROAM_GRAPH_NAME: 그래프 이름

Roam API 토큰 얻기

1. https://roamresearch.com/#/app 에서 그래프 열기
2. Settings > "Graph" 탭 > "API Tokens" 섹션
3. "+ New API Token" 버튼 클릭
4. "Access Scope"을 "read"에서 "edit"로 변경

사용 방법

로컬 실행 (개발)

npm run dev

프로덕션 빌드

npm run build
npm start

Railway 배포

1. Railway 계정 생성
2. 새 프로젝트 생성
3. GitHub 저장소 연결
4. 환경 변수 설정:
   • ROAM_API_TOKEN
   • ROAM_GRAPH_NAME
   • SERVER_MODE=http

Claude와 연결하기

로컬 MCP 설정

Claude Desktop의 설정 파일에 다음 추가:

{
  "mcpServers": {
    "roam": {
      "command": "node",
      "args": ["/path/to/roam-mcp-server/dist/index.js"],
      "env": {
        "ROAM_API_TOKEN": "your_token",
        "ROAM_GRAPH_NAME": "your_graph_name"
      }
    }
  }
}

Railway HTTP 연결

Railway 배포 후 URL을 사용하여 연결:

{
  "mcpServers": {
    "roam": {
      "url": "https://your-app.railway.app"
    }
  }
}

사용 가능한 도구

검색 도구

• search_pages: 페이지 제목 검색
• search_all: 전체 내용 검색 (페이지 + 블록)
• search_by_tag: 특정 태그로 검색
• search_by_tags: 여러 태그로 검색 (AND 조건)

페이지 관리

• create_page: 새 페이지 생성
• get_page: 페이지 기본 내용 가져오기
• get_page_full_content: 페이지 전체 내용을 마크다운으로 가져오기

블록 관리

• create_block: 페이지에 블록 추가
• create_block_with_auto_tags: 자동 태그 분석과 함께 블록 추가
• update_block: 블록 내용 업데이트
• delete_block: 블록 삭제

Daily Note

• add_to_daily_note: Daily Note에 블록 추가
• add_to_daily_note_with_auto_tags: 자동 태그 분석과 함께 Daily Note에 추가

자동 태그 시스템

시스템이 자동으로 인식하는 키워드와 태그:

한국어 키워드

• 회의, 미팅 → #회의 #미팅
• 아이디어, 생각 → #아이디어 #생각
• 프로젝트, 작업 → #프로젝트 #작업
• 질문, 궁금 → #질문 #궁금
• 중요, 핵심 → #중요 #핵심
• 긴급, 시급 → #긴급 #시급

영어 키워드

• meeting → #회의 #미팅
• todo → #할일 #TODO
• idea → #아이디어 #생각
• project → #프로젝트 #작업
• important → #중요 #핵심

패턴 감지

• URL (http/https) → #링크
• 코드 블록 (``` 또는 ) → #코드`
• 날짜 (YYYY-MM-DD, MM월 DD일) → #일정

주의사항

• API 토큰은 절대 공개 저장소에 커밋하지 마세요
• 암호화된 그래프는 지원되지 않습니다
• API 토큰은 그래프 소유자만 생성할 수 있습니다