Skip to main content
Glama

Roam Research MCP 서버

npm 버전 프로젝트 상태: 진행 중 – 초기 개발이 진행 중이지만, 아직 대중에게 적합하고 안정적이며 사용 가능한 릴리스가 나오지 않았습니다. 라이센스: MIT 깃허브

Roam Research의 API 기능에 대한 포괄적인 접근을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 통해 Claude와 같은 AI 비서가 표준화된 인터페이스를 통해 Roam Research 그래프와 상호 작용할 수 있습니다. (현재 진행 중인 개인 프로젝트이며 Roam Research의 공식 승인을 받지 않았습니다.)

설치

패키지를 글로벌하게 설치할 수 있습니다:

지엑스피1

또는 저장소를 복제하고 소스에서 빌드합니다.

git clone https://github.com/2b3pro/roam-research-mcp.git
cd roam-research-mcp
npm install
npm run build

Related MCP server: Roam Research MCP Server

테스트하려면

빌드 후 MCP Inspector를 실행합니다.

npx @modelcontextprotocol/inspector node build/index.js

특징

이 서버는 Roam Research와 상호 작용하기 위한 강력한 도구를 제공합니다.

  • .env 지원을 통한 환경 변수 처리

  • 포괄적인 입력 검증

  • 대소문자 구분 없이 페이지 제목 일치

  • 재귀적 블록 참조 해결

  • 마크다운 구문 분석 및 변환

  • 일일 페이지 통합

  • 자세한 디버그 로깅

  • 효율적인 배치 작업

  • 계층적 개요 생성

  1. roam_fetch_page_by_title : 제목별로 페이지의 콘텐츠를 가져와서 읽고, 최대 4단계 깊이까지 블록 참조를 재귀적으로 확인합니다.

  2. roam_create_page : 선택적 콘텐츠로 새 페이지를 만듭니다.

  3. roam_create_block : 페이지에 새로운 블록을 생성합니다(기본값은 오늘의 일일 페이지입니다)

  4. roam_import_markdown : 특정 블록 아래에 중첩된 마크다운 콘텐츠를 가져옵니다.

  5. roam_add_todo : 체크박스 구문을 사용하여 오늘의 일일 페이지에 여러 개의 할 일 항목을 추가합니다.

  6. roam_create_outline : 적절한 중첩 및 구조를 사용하여 계층적 개요를 만듭니다.

  7. roam_search_block_refs : 페이지 내 또는 그래프 전체에서 블록 참조를 검색합니다.

  8. roam_search_hierarchy : 블록 부모-자식 관계를 탐색하고 검색합니다.

  9. roam_find_pages_modified_today : 오늘 자정 이후 수정된 모든 페이지를 찾습니다.

  10. roam_search_by_text : 모든 페이지 또는 특정 페이지 내에서 특정 텍스트가 포함된 블록을 검색합니다.

  11. roam_update_block : 직접 텍스트 또는 패턴 기반 변환으로 블록 콘텐츠 업데이트

  12. roam_search_by_date : 생성 또는 수정 날짜를 기준으로 블록 및 페이지 검색

  13. roam_search_for_tag : 근처 태그로 선택적으로 필터링하여 특정 태그가 포함된 블록을 검색합니다.

  14. roam_remember : 자동 태그 지정으로 기억이나 정보를 저장하고 분류합니다.

  15. roam_recall : MEMORIES_TAG 태그로 표시된 블록(아래 참조) 또는 같은 이름의 페이지 제목에 있는 블록의 메모리를 회수합니다.

  16. roam_datomic_query : 고급 데이터 검색 및 분석을 위해 Roam 그래프에서 사용자 정의 Datalog 쿼리를 실행합니다.

설정

  1. Roam Research API 토큰을 생성하세요:

    • 그래프 설정으로 이동하세요

    • "API 토큰" 섹션으로 이동합니다(설정 > "그래프" 탭 > "API 토큰" 섹션을 클릭하고 "+ 새 API 토큰" 버튼을 클릭합니다)

    • 새로운 토큰을 생성하세요

  2. 환경 변수 구성: 필요한 환경 변수를 구성하는 데는 두 가지 옵션이 있습니다.

    옵션 1: .env 파일 사용(개발에 권장) roam-research 디렉터리에 .env 파일을 만듭니다.

    ROAM_API_TOKEN=your-api-token
    ROAM_GRAPH_NAME=your-graph-name
    MEMORIES_TAG='#[[LLM/Memories]]'

    옵션 2: MCP 설정 사용(대체 방법) MCP 설정 파일에 구성을 추가합니다.

    • Cline의 경우( ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ):

    • Claude 데스크톱 앱( ~/Library/Application Support/Claude/claude_desktop_config.json ):

    {
      "mcpServers": {
        "roam-research": {
          "command": "node",
          "args": ["/path/to/roam-research-mcp/build/index.js"],
          "env": {
            "ROAM_API_TOKEN": "your-api-token",
            "ROAM_GRAPH_NAME": "your-graph-name",
            "MEMORIES_TAG": "#[[LLM/Memories]]"
          }
        }
      }
    }

    참고: 서버는 먼저 .env 파일에서 로드를 시도한 다음 MCP 설정의 환경 변수를 사용합니다.

  3. 서버를 빌드합니다(MCP의 루트 디렉토리에 있는지 확인하세요):

    cd roam-research-mcp
    npm install
    npm run build

용법

제목으로 페이지 가져오기

해결된 블록 참조로 페이지의 콘텐츠를 가져와서 읽습니다.

use_mcp_tool roam-research roam_fetch_page_by_title {
  "title": "Example Page"
}

다음을 사용하여 페이지 내용을 마크다운으로 반환합니다.

  • 완전한 계층 구조

  • 블록 참조는 재귀적으로 해결됨(최대 4단계 깊이)

  • 중첩 수준에 대한 적절한 들여쓰기

  • 전체 마크다운 서식

페이지 만들기

선택적인 콘텐츠로 새 페이지를 만드세요:

use_mcp_tool roam-research roam_create_page {
  "title": "New Page",
  "content": "Initial content for the page"
}

성공시 생성된 페이지의 UID를 반환합니다.

블록 생성

페이지에 새 블록을 추가합니다(page_uid나 title이 제공되지 않으면 오늘의 일일 페이지가 기본값으로 설정됨):

use_mcp_tool roam-research roam_create_block {
  "content": "Block content",
  "page_uid": "optional-target-page-uid",
  "title": "optional-target-page-title"
}

다음 중 하나를 지정할 수 있습니다.

  • page_uid : 대상 페이지에 대한 직접 참조

  • title : 대상 페이지의 이름 (존재하지 않으면 생성됩니다)

  • 둘 다 아님: 블록이 오늘의 일일 페이지에 추가됩니다.

보고:

{
  "success": true,
  "block_uid": "created-block-uid",
  "parent_uid": "parent-page-uid"
}

개요 만들기

적절한 중첩과 구조를 갖춘 계층적 개요를 만듭니다.

use_mcp_tool roam-research roam_create_outline {
  "outline": [
    {
      "text": "I. Top Level",
      "level": 1
    },
    {
      "text": "A. Second Level",
      "level": 2
    },
    {
      "text": "1. Third Level",
      "level": 3
    }
  ],
  "page_title_uid": "optional-target-page",
  "block_text_uid": "optional-header-text"
}

특징:

  • 최대 10단계의 중첩으로 복잡한 윤곽선을 만듭니다.

  • 개요 구조와 내용 검증

  • 올바른 부모-자녀 관계 유지

  • 개요에 대한 선택적 헤더 블록

  • 페이지가 지정되지 않으면 오늘의 일일 페이지로 기본 설정됩니다.

  • 블록 생성을 위한 효율적인 일괄 작업

매개변수:

  • outline : 개요 항목의 배열, 각 항목에는 다음이 포함됩니다.

    • text : 개요 항목의 내용(필수)

    • level : 중첩 레벨(1-10, 필수)

  • page_title_uid : 대상 페이지 제목 또는 UID(선택 사항, 기본값은 오늘 페이지)

  • block_text_uid : 개요의 헤더 텍스트(선택 사항)

보고:

{
  "success": true,
  "page_uid": "target-page-uid",
  "parent_uid": "header-block-uid",
  "created_uids": ["uid1", "uid2", ...]
}

할 일 항목 추가

오늘의 일일 페이지에 하나 이상의 할 일 항목을 추가하세요.

use_mcp_tool roam-research roam_add_todo {
  "todos": [
    "First todo item",
    "Second todo item",
    "Third todo item"
  ]
}

특징:

  • Roam 체크박스 구문을 사용하여 할 일을 추가합니다( {{TODO}} todo text ).

  • 단일 작업에서 여러 개의 할 일 추가 지원

  • 10개 이상의 할 일을 추가할 때 효율성을 위해 일괄 작업을 사용합니다.

  • 오늘의 페이지가 존재하지 않으면 자동으로 오늘의 페이지를 생성합니다.

  • 순차적으로 최상위 블록으로 할 일을 추가합니다.

중첩된 마크다운 가져오기

특정 블록 아래에 중첩된 마크다운 콘텐츠를 가져옵니다.

use_mcp_tool roam-research roam_import_markdown {
  "content": "- Item 1\n  - Subitem A\n  - Subitem B\n- Item 2",
  "page_uid": "optional-page-uid",
  "page_title": "optional-page-title",
  "parent_uid": "optional-parent-block-uid",
  "parent_string": "optional-exact-block-content",
  "order": "first"
}

특징:

  • 특정 블록 아래의 콘텐츠 가져오기:

    • UID 또는 정확한 문자열 일치로 부모 블록 찾기

    • 제목이나 UID로 특정 페이지 내 블록 찾기

    • 페이지가 지정되지 않으면 오늘 페이지로 기본 설정됩니다.

  • 콘텐츠 배치 제어:

    • 부모 블록의 첫 번째 또는 마지막 자식으로 추가

    • 계층 구조 유지

    • 중첩된 콘텐츠에 대한 효율적인 일괄 작업

  • 포괄적인 반환 값:

    {
      "success": true,
      "page_uid": "target-page-uid",
      "parent_uid": "parent-block-uid",
      "created_uids": ["uid1", "uid2", ...]
    }

매개변수:

  • content : 가져올 중첩된 마크다운 콘텐츠

  • page_uid : 부모 블록이 포함된 페이지의 UID

  • page_title : 부모 블록이 포함된 페이지의 제목(page_uid가 제공된 경우 무시됨)

  • parent_uid : 콘텐츠를 추가할 부모 블록의 UID

  • parent_string : 부모 블록의 정확한 문자열 내용(page_uid 또는 page_title을 제공해야 함)

  • order : 콘텐츠를 추가할 위치("first" 또는 "last", 기본값은 "first")

블록 참조 검색

페이지 내 또는 전체 그래프에서 블록 참조를 검색합니다.

use_mcp_tool roam-research roam_search_block_refs {
  "block_uid": "optional-block-uid",
  "page_title_uid": "optional-page-title-or-uid"
}

특징:

  • 특정 블록에 대한 모든 참조 찾기

  • 페이지 내에서 블록 참조를 검색합니다.

  • 그래프 전체에서 검색

  • 직접 및 간접 참조를 모두 지원합니다.

  • 블록 콘텐츠와 위치 컨텍스트가 포함됩니다.

매개변수:

  • block_uid : 참조를 찾을 블록의 UID(선택 사항)

  • page_title_uid : 검색할 페이지의 제목 또는 UID(선택 사항)

보고:

{
  "success": true,
  "matches": [
    {
      "block_uid": "referenced-block-uid",
      "content": "Block content with ((reference))",
      "page_title": "Page containing reference"
    }
  ],
  "message": "Found N block(s) referencing..."
}

텍스트로 검색

모든 페이지 또는 특정 페이지 내에서 특정 텍스트가 포함된 블록을 검색합니다.

use_mcp_tool roam-research roam_search_by_text {
  "text": "search text",
  "page_title_uid": "optional-page-title-or-uid",
  "case_sensitive": true
}

특징:

  • 그래프의 모든 블록에서 모든 텍스트를 검색합니다.

  • 선택적인 페이지 범위 검색

  • 대소문자 구분 또는 대소문자 구분 안 함 검색

  • 페이지 컨텍스트를 사용하여 블록 콘텐츠를 반환합니다.

  • Datalog 쿼리를 사용한 효율적인 텍스트 매칭

매개변수:

  • text : 검색할 텍스트(필수)

  • page_title_uid : 검색할 페이지의 제목 또는 UID(선택 사항)

  • case_sensitive : 대소문자 구분 검색을 수행할지 여부(선택 사항, 기본값: Roam의 기본 동작과 일치하려면 true)

보고:

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing search text",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) containing \"search text\""
}

블록 콘텐츠 업데이트

직접 텍스트 교체나 패턴 기반 변환을 사용하여 블록의 콘텐츠를 업데이트합니다.

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "content": "New block content"
}

또는 패턴 기반 변환을 사용합니다.

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "transform_pattern": {
    "find": "\\bPython\\b",
    "replace": "[[Python]]",
    "global": true
  }
}

특징:

  • 두 가지 업데이트 모드:

    • 직접 콘텐츠 교체

    • 정규식을 사용한 패턴 기반 변환

  • 업데이트하기 전에 블록 존재 여부를 확인하세요

  • 업데이트된 콘텐츠를 응답으로 반환합니다.

  • 글로벌 또는 단일 매치 교체 지원

  • 블록 관계 및 메타데이터 보존

매개변수:

  • block_uid : 업데이트할 블록의 UID(필수)

  • content : 블록에 대한 새 콘텐츠(직접 교체를 사용하는 경우)

  • transform_pattern : 기존 콘텐츠를 변환하기 위한 패턴:

    • find : 찾을 텍스트 또는 정규식 패턴

    • replace : 바꿀 텍스트

    • global : 모든 항목을 바꿀지 여부(기본값: true)

보고:

{
  "success": true,
  "content": "Updated block content"
}

태그 검색

근처 태그로 선택적으로 필터링하여 특정 태그가 포함된 블록을 검색하세요.

use_mcp_tool roam-research roam_search_for_tag {
  "primary_tag": "Project/Tasks",
  "page_title_uid": "optional-page-title-or-uid",
  "near_tag": "optional-secondary-tag",
  "case_sensitive": true
}

특징:

  • 특정 태그가 포함된 블록 검색

  • 다른 태그의 존재 여부에 따른 선택적 필터링

  • 페이지 범위 또는 그래프 전체 검색

  • 대소문자 구분 또는 대소문자 구분 안 함 검색

  • 페이지 컨텍스트를 사용하여 블록 콘텐츠를 반환합니다.

  • Datalog 쿼리를 사용한 효율적인 태그 매칭

매개변수:

  • primary_tag : 검색할 주요 태그(필수)

  • page_title_uid : 검색할 페이지의 제목 또는 UID(선택 사항)

  • near_tag : 결과를 필터링할 또 다른 태그(선택 사항)

  • case_sensitive : 대소문자 구분 검색을 수행할지 여부(선택 사항, 기본값: Roam의 기본 동작과 일치하려면 true)

보고:

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing #[[primary_tag]]",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) referencing \"primary_tag\""
}

정보 기억하기

자동 태그 지정 및 분류를 통해 추억이나 중요한 정보를 저장하세요.

use_mcp_tool roam-research roam_remember {
  "memory": "Important information to remember",
  "categories": ["Work", "Project/Alpha"]
}

특징:

  • #[[LLM/Memories]] 태그로 정보를 저장합니다.

  • 조직을 위한 선택적 카테고리 태그 추가

  • 오늘의 일일 페이지에 자동으로 추가됩니다

  • 메모리당 여러 카테고리 지원

  • roam_search_for_tag를 사용하여 쉽게 검색

  • 기억의 연대순을 유지합니다

매개변수:

  • memory : 기억할 정보 (필수)

  • categories : 메모리에 태그를 지정할 카테고리의 선택적 배열

보고:

{
  "success": true,
  "block_uid": "created-block-uid",
  "content": "Memory content with tags"
}

날짜로 검색

생성 또는 수정 날짜를 기준으로 블록 및 페이지 검색:

use_mcp_tool roam-research roam_search_by_date {
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "type": "modified",
  "scope": "blocks",
  "include_content": true
}

특징:

  • 생성 날짜, 수정 날짜 또는 둘 다로 검색

  • 블록, 페이지 또는 둘 다 필터링

  • 시작 및 종료 날짜가 포함된 선택적 날짜 범위

  • 결과에 블록/페이지 콘텐츠 포함 또는 제외

  • 타임스탬프별로 결과 정렬

  • Datalog 쿼리를 사용한 효율적인 날짜 기반 필터링

매개변수:

  • start_date : ISO 형식(YYYY-MM-DD)의 시작 날짜(필수)

  • end_date : ISO 형식(YYYY-MM-DD)의 종료 날짜(선택 사항)

  • type : '생성됨', '수정됨', '둘 다'로 검색할지 여부 (필수)

  • scope : '블록', '페이지' 또는 '둘 다'를 검색할지 여부(필수)

  • include_content : 일치하는 블록/페이지의 콘텐츠를 포함할지 여부(선택 사항, 기본값: true)

보고:

{
  "success": true,
  "matches": [
    {
      "uid": "block-or-page-uid",
      "type": "block",
      "time": 1704067200000,
      "content": "Block or page content",
      "page_title": "Page title (for blocks)"
    }
  ],
  "message": "Found N matches for the given date range and criteria"
}

오늘 수정된 페이지 찾기

오늘 자정 이후 수정된 모든 페이지를 찾으세요:

use_mcp_tool roam-research roam_find_pages_modified_today {}

특징:

  • 자정 이후 페이지에 적용된 모든 수정 사항을 추적합니다.

  • 블록 계층의 모든 레벨에서 변경 사항을 감지합니다.

  • 수정된 페이지 제목의 고유한 목록을 반환합니다.

  • 수정된 페이지 수 포함

  • 매개변수가 필요하지 않습니다

보고:

{
  "success": true,
  "pages": ["Page 1", "Page 2"],
  "message": "Found 2 page(s) modified today"
}

데이터 쿼리 실행

고급 데이터 검색 및 분석을 위해 Roam 그래프에서 사용자 정의 Datalog 쿼리를 실행하세요.

use_mcp_tool roam-research roam_datomic_query {
  "query": "[:find (count ?p)\n :where [?p :node/title]]",
  "inputs": []
}

특징:

  • Roam의 쿼리 엔진에 직접 액세스

  • 모든 Datalog 쿼리 기능 지원:

    • 복잡한 패턴 매칭

    • 집계 함수(count, sum, max, min, avg, distinct)

    • 문자열 연산(includes?, starts-with?, ends-with?)

    • 논리 연산(<, >, <=, >=, =, not=)

    • 재귀 쿼리에 대한 규칙

  • 대소문자 구분 및 대소문자 구분 안 함 검색 기능

  • 그래프 전체에 걸친 효율적인 쿼리

매개변수:

  • query : 실행할 Datalog 쿼리(필수)

  • inputs : 쿼리에 대한 입력 매개변수의 선택적 배열

보고:

{
  "success": true,
  "matches": [
    {
      "content": "[result data]",
      "block_uid": "",
      "page_title": ""
    }
  ],
  "message": "Query executed successfully. Found N results."
}

예시 쿼리:

  1. 모든 페이지 수 세기:

[:find (count ?p)
 :where [?p :node/title]]
  1. 대소문자를 구분하지 않는 텍스트 검색:

[:find ?string ?title
 :where
 [?b :block/string ?string]
 [(clojure.string/lower-case ?string) ?lower]
 [(clojure.string/includes? ?lower "search term")]
 [?b :block/page ?p]
 [?p :node/title ?title]]
  1. 날짜 이후에 수정된 블록 찾기:

[:find ?block_ref ?string
 :in $ ?start_of_day
 :where
 [?b :edit/time ?time]
 [(> ?time ?start_of_day)]
 [?b :block/uid ?block_ref]
 [?b :block/string ?string]]

더 많은 쿼리 예제와 구문 설명서는 Roam_Research_Datalog_Cheatsheet.md를 참조하세요.

검색 블록 계층 구조

블록 부모-자식 관계를 탐색하고 검색합니다.

use_mcp_tool roam-research roam_search_hierarchy {
  "parent_uid": "optional-parent-block-uid",
  "child_uid": "optional-child-block-uid",
  "page_title_uid": "optional-page-title-or-uid",
  "max_depth": 3
}

특징:

  • 블록 계층을 위아래로 검색

  • 특정 블록의 자식 찾기

  • 특정 블록의 부모 찾기

  • 검색 깊이 구성(1~10단계)

  • 선택적 페이지 범위 필터링

  • 각 결과에 대한 심층 정보가 포함되어 있습니다.

매개변수:

  • parent_uid : 자식을 찾을 블록의 UID(아래로 검색하는 경우 필수)

  • child_uid : 부모를 찾을 블록의 UID(위로 검색하는 경우 필수)

  • page_title_uid : 검색할 페이지의 제목 또는 UID(선택 사항)

  • max_depth : 검색할 깊이 수준(선택 사항, 기본값: 1, 최대: 10)

보고:

{
  "success": true,
  "matches": [
    {
      "block_uid": "related-block-uid",
      "content": "Block content",
      "depth": 2,
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) as children/parents..."
}

오류 처리

서버는 일반적인 시나리오에 대한 포괄적인 오류 처리를 제공합니다.

  • 구성 오류:

    • API 토큰 또는 그래프 이름이 없습니다.

    • 잘못된 환경 변수

  • API 오류:

    • 인증 실패

    • 잘못된 요청

    • 실패한 작업

  • 도구별 오류:

    • 페이지를 찾을 수 없습니다(대소문자 구분 없이 검색)

    • 문자열 일치로 블록을 찾을 수 없습니다.

    • 잘못된 마크다운 형식

    • 필수 매개변수가 없습니다

    • 잘못된 개요 구조 또는 내용

각 오류 응답에는 다음이 포함됩니다.

  • 표준 MCP 오류 코드

  • 자세한 오류 메시지

  • 해당되는 경우 해결을 위한 제안

개발

건물

서버를 빌드하려면:

npm install
npm run build

이렇게 하면:

  1. 필요한 모든 종속성을 설치하세요

  2. TypeScript를 JavaScript로 컴파일

  3. 출력 파일을 실행 가능하게 만들기

개발 중에 npm run watch 사용하면 파일이 변경되면 자동으로 다시 컴파일할 수도 있습니다.

MCP Inspector로 테스트

MCP Inspector는 MCP 서버를 테스트하고 디버깅하는 데 도움이 되는 도구입니다. 서버를 테스트하려면 다음을 수행하세요.

# Inspect with npx:
npx @modelcontextprotocol/inspector node build/index.js

이렇게 하면:

  1. 서버를 검사기 모드로 시작합니다.

  2. 다음에 대한 대화형 인터페이스를 제공합니다.

    • 사용 가능한 도구 및 리소스 나열

    • 사용자 정의 매개변수로 도구 실행

    • 도구 응답 및 오류 처리 보기

특허

MIT 라이센스

Available Tools

25 tools
roam_add_todoA

Add a list of todo items as individual blocks to today's daily page in Roam. Each item becomes its own actionable block with todo status. NOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use alias syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: todos (required), graph, write_key. Returns: success

roam_create_outlineA

Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. To create a new page with an outline, use the roam_create_page tool instead. The outline parameter defines new blocks to be created. To nest content under an existing block, provide its UID or exact text in block_text_uid, and ensure the outline array contains only the child blocks with levels relative to that parent. Including the parent block's text in the outline array will create a duplicate block. Best for:

  • Adding supplementary structured content to existing pages

  • Creating temporary or working outlines (meeting notes, brainstorms)

  • Organizing thoughts or research under a specific topic

  • Breaking down subtopics or components of a larger concept Best for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider roam_process_batch_actions instead. API Usage Note: This tool performs verification queries after creation. For large outlines (10+ items) or when rate limits are a concern, consider using roam_process_batch_actions instead to minimize API calls.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: outline (required), graph, order, write_key, +2 more. Returns: success, page_uid, parent_uid, created_blocks

roam_create_pageA

Create a new standalone page in Roam with optional content, including structured outlines and tables, using explicit nesting levels and headings (H1-H3). This is the preferred method for creating a new page with an outline in a single step. Best for:

  • Creating foundational concept pages that other pages will link to/from

  • Establishing new topic areas that need their own namespace

  • Setting up reference materials or documentation

  • Making permanent collections of information

  • Creating pages with mixed text and table content in one call. Efficiency Tip: This tool batches page and content creation efficiently. For adding content to existing pages, use roam_process_batch_actions instead.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: title (required), graph, content, write_key. Returns: success, page_uid

roam_create_tableA

Create a table in Roam with specified headers and rows. This tool abstracts the complex nested structure that Roam tables require, making it much easier to create properly formatted tables.

Why use this tool:

  • Roam tables require precise nested block structures that are error-prone to create manually

  • Automatically handles the {{[[table]]}} container and nested column structure

  • Validates row/column consistency before execution

  • Converts empty cells to spaces (required by Roam)

Example: A table with headers ["", "Column A", "Column B"] and rows [{label: "Row 1", cells: ["A1", "B1"]}] creates a 2x3 table.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: rows (required), headers (required), parent_uid (required), graph, +2 more. Returns: error, success, uid_map, committed, +3 more

roam_datomic_queryA
Read-onlyIdempotent

Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam's query engine. Note: Roam graph is case-sensitive.

Optimal Use Cases for roam_datomic_query:

  • Advanced Filtering (including Regex): Use for scenarios requiring complex filtering, including regex matching on results post-query, which Datalog does not natively support for all data types. It can fetch broader results for client-side post-processing.

  • Highly Complex Boolean Logic: Ideal for intricate combinations of "AND", "OR", and "NOT" conditions across multiple terms or attributes.

  • Arbitrary Sorting Criteria: The go-to for highly customized sorting needs beyond default options.

  • Proximity Search: For advanced search capabilities involving proximity, which are difficult to implement efficiently with simpler tools.

List of some of Roam's data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text). Predicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=). Aggregates (distinct, count, sum, max, min, avg, limit). Tips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: query (required), graph, inputs, write_key, +3 more.

roam_fetch_blockA
Read-onlyIdempotent

Fetch a block by its UID with optional children (down to a specified depth) and/or ancestors (up to page root). Returns the block's UID, text, order, children array, and optionally an ancestors array with the chain to the page root.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: block_uid (required), depth, graph, write_key, +1 more.

roam_fetch_page_by_titleA
Read-onlyIdempotent

Fetch page by title. Returns content in the specified format.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: title (required), graph, format, write_key.

roam_fetch_page_full_viewA
Read-onlyIdempotent

Fetch a complete page view that mirrors what Roam Research shows in its UI: the page's own content, plus all linked references (backlinks) grouped by source page, each with their ancestor breadcrumb context and children expanded to the specified depth. Use this when you need the full picture of a page — both what is written on it and everything else in the graph that references it.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: title (required), graph, write_key, children_depth, +1 more.

roam_find_pages_modified_todayA
Read-onlyIdempotent

Find pages that have been modified today (since midnight), with pagination and sorting options.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, limit, offset, write_key, +1 more.

roam_get_guidelinesA
Read-onlyIdempotent

Retrieve this graph's user-defined agent conventions, read from the [[roam/agent guidelines]] page inside the graph (configurable per graph). These are the user's own rules — how they tag, how they name and namespace pages, what to never do, how they want your voice attributed.

Also returns roamSyntax: the rules whose violation destroys content — whole-page rewrites that delete, truncated previews written back as content, retyped block references, and the syntax that differs from standard markdown. These are returned on every call, including when the graph has no guidelines page, and they hold regardless of what the conventions say.

Call this ONCE per graph per session, before other tools, INCLUDING for reads: conventions change how results should be interpreted and presented, not just how content is written. Returns today's daily note title as orientation.

Distinct from roam_markdown_cheatsheet, which is the complete syntax reference — components, queries, embeds, tool selection. Call that when you need to look something up; this one you need before writing at all. Returns exists:false rather than failing when no page has been created.

Inputs: graph, write_key.

roam_get_subpagesA
Read-onlyIdempotent

Fetch all sub-pages (namespace children) of a given page prefix. Matches by page title prefix — pages titled "Prefix/Something" are sub-pages of "Prefix" and appear in the Hierarchy section of that page. This is namespace/title-prefix matching, distinct from roam_search_hierarchy which traverses block parent/child relationships. Optionally filter to only sub-pages containing a specific tag (e.g. filter active projects with filter_tag="active"), and optionally include each sub-page's full block content.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: prefix (required), graph, write_key, filter_tag, +1 more.

roam_import_markdownA

Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page. If a parent_string is provided and the block does not exist, it will be created. Returns a nested structure of the created blocks. API Usage Note: This tool fetches the full nested structure after import for verification. For large imports or when rate limits are a concern, consider using roam_process_batch_actions with pre-structured actions instead.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: content (required), graph, order, page_uid, +4 more. Returns: success, page_uid, parent_uid, created_blocks

roam_markdown_cheatsheetA
Read-onlyIdempotent

Provides the comprehensive Roam syntax reference. Covers: formatting, links & references (page refs, block refs, embeds including embed-children and embed-path), tags, dates, tasks, callouts, attributes, queries (native {{query}} with its clause rules and page-ref inheritance, plus :q Datalog tables with built-in rules), tables, kanban, mermaid diagrams (with theme support), advanced components (dropdowns, tooltips, templates, document mode, word-count), CSS tags (#.rm-E, #.rm-hide, etc.), anti-patterns, tool selection guide, and API efficiency tips.

IMPORTANT: Always load this cheatsheet before creating or updating Roam content. It prevents common syntax errors and guides tool selection.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, write_key.

roam_move_blockA
DestructiveIdempotent

Move a block to a new location (different parent or position). This is a convenience wrapper around roam_process_batch_actions for single block moves.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: block_uid (required), parent_uid (required), graph, order, +1 more. Returns: order, success, block_uid, new_parent_uid

roam_process_batch_actionsA
Destructive

RATE LIMIT EFFICIENT: This is the most API-efficient tool for multiple block operations. Combine all create/update/delete operations into a single call whenever possible. For intensive page updates or revisions, prefer this tool over multiple sequential calls.

Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order.

UID Placeholders for Nested Blocks: Use {{uid:name}} syntax for parent-child references within the same batch. The server generates proper random UIDs and returns a uid_map showing placeholder→UID mappings. Example: { uid: "{{uid:parent1}}", string: "Parent" } then { location: { "parent-uid": "{{uid:parent1}}" }, string: "Child" }. Response includes { success: true, uid_map: { "parent1": "Xk7mN2pQ9" } }.

For actions on existing blocks, a valid block UID is required. Note: Roam-flavored markdown, including block embedding with ((UID)) syntax, is supported within the string property for create-block and update-block actions. For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs. Tools like roam_fetch_page_by_title or other search tools can be used to retrieve these UIDs before executing batch actions. For simpler, sequential outlines, roam_create_outline is often more suitable.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: actions (required), graph, write_key. Returns: error, success, uid_map, committed, +2 more

roam_recallA
Read-onlyIdempotent

Retrieve all stored memories on page titled ROAM_MEMORIES_TAG, or tagged block content with the same name. Returns a combined, deduplicated list of memories. Optionally filter blocks with a specific tag and sort by creation date.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, sort_by, write_key, filter_tag.

roam_rememberA

Add a memory or piece of information to remember, stored on the daily page with ROAM_MEMORIES_TAG tag and optional categories (unless include_memories_tag is false). NOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use alias syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: memory (required), graph, heading, write_key, +3 more. Returns: success, block_uid, parent_uid

roam_rename_pageA
DestructiveIdempotent

Rename a page by changing its title. Identifies the page by current title or UID.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: new_title (required), uid, graph, old_title, +1 more. Returns: message, success

roam_search_block_refsA
Read-onlyIdempotent

Search for block references within a page or across the entire graph. Can search for references to a specific block, a page title, or find all block references.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, title, block_uid, write_key, +1 more.

roam_search_by_dateA
Read-onlyIdempotent

Search for blocks or pages based on creation or modification dates. Not for daily pages with ordinal date titles.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: type (required), scope (required), start_date (required), graph, +3 more.

roam_search_by_statusA
Read-onlyIdempotent

Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: status (required), graph, exclude, include, +2 more.

roam_search_by_textA
Read-onlyIdempotent

Search for blocks containing specific text across all pages or within a specific page. Use scope: "page_titles" to search for pages by namespace prefix (e.g., "Convention/" finds all pages starting with that prefix). This tool supports pagination via the limit and offset parameters. Pagination follows hidden-block filtering; block results use UID order and namespace results use title order.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: text (required), graph, limit, scope, +4 more.

roam_search_for_tagA
Read-onlyIdempotent

Search for blocks containing a specific tag. Use primary_tag for the tag to find, and optionally page_title_uid to limit search to a specific page. Supports pagination via limit and offset, applied after hidden-block filtering in UID order. Use this tool to search for memories tagged with the ROAM_MEMORIES_TAG.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: primary_tag (required), graph, limit, offset, +4 more.

roam_search_hierarchyA
Read-onlyIdempotent

Search for parent or child blocks in the block hierarchy. Can search up or down the hierarchy from a given block.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, child_uid, max_depth, write_key, +2 more.

roam_update_page_markdownA
DestructiveIdempotent

Update an existing page with new markdown content using smart diff. Preserves block UIDs where possible and generates minimal changes. This is ideal for:

  • Syncing external markdown files to Roam

  • AI-assisted content updates that preserve references

  • Batch content modifications without losing block references

⚠️ This REPLACES the page, it does not append. Any block your markdown does not account for is deleted. Pass the complete intended page, or use roam_process_batch_actions / roam_create_outline to change only part of one. Use dry_run: true to see the actions first.

How it works:

  1. Fetches existing page blocks

  2. Matches new content to existing blocks by text similarity

  3. Generates minimal create/update/move/delete operations

  4. Preserves UIDs for matched blocks (keeping references intact)

#.rm-hide / #.rm-private subtrees are excluded from the diff and left untouched — you cannot see them, so you cannot be asked to account for them. preserved_hidden reports how many, when any.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: title (required), markdown (required), graph, dry_run, +1 more. Returns: stats, actions, success, summary, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools target distinct resources or actions, and the descriptions explicitly differentiate nearby tools such as roam_create_page vs. roam_create_outline vs. roam_process_batch_actions, and roam_fetch_page_by_title vs. roam_fetch_page_full_view. Some overlap remains, especially between namespace/page-title search and subpage retrieval, or between date search and modified-today search, but the boundaries are generally clear enough for tool selection.

    Naming Consistency4/5

    All tools share a consistent roam_ prefix and snake_case formatting, which makes the set predictable. The pattern is mostly roam_verb_noun, though a few names such as roam_markdown_cheatsheet and roam_datomic_query are noun-oriented rather than strict verb-object forms.

    Tool Count3/5

    With 25 tools, this is a heavy surface for an MCP server, even for a complex graph tool like Roam. The tools are mostly justified by distinct operations, but the set is large enough that an agent may need extra care to choose efficiently, especially across the many search and content-creation variants.

    Completeness4/5

    The surface covers most core Roam workflows: page creation, fetching, renaming, markdown updates, block fetching, moving, searching, batch block operations, tables, todos, memories, and references. Minor gaps remain, such as no explicit page deletion tool and block updates/deletes only being exposed through the broader batch-actions tool.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables Claude Desktop to read from and write to Roam Research graphs, allowing for retrieving page content, finding references, and adding blocks to existing or daily pages.
      4
      1
      -
    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with Roam Research graphs through comprehensive API access, supporting page/block operations, markdown import, search, memory storage, and complex batch actions for managing knowledge graphs.
      18
      404 npm
      -