Skip to main content
Glama

Roam Research MCP サーバー

npmバージョン プロジェクトの状態: WIP – 初期開発は進行中ですが、一般公開に適した安定した使用可能なリリースはまだありません。 ライセンス: MIT GitHub

Roam ResearchのAPI機能への包括的なアクセスを提供するモデルコンテキストプロトコル(MCP)サーバー。このサーバーにより、ClaudeのようなAIアシスタントが、標準化されたインターフェースを介してRoam Researchのグラフと対話できるようになります。(Roam Researchによる公式承認を受けていない、現在進行中の個人プロジェクトです。)

インストール

パッケージをグローバルにインストールできます。

npm install -g roam-research-mcp

または、リポジトリをクローンしてソースからビルドします。

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 サポートによる環境変数の処理

  • 包括的な入力検証

  • 大文字と小文字を区別しないページタイトルの一致

  • 再帰ブロック参照解決

  • Markdownの解析と変換

  • 毎日のページ統合

  • 詳細なデバッグログ

  • 効率的なバッチ操作

  • 階層的なアウトラインの作成

  1. roam_fetch_page_by_title : ページのコンテンツをタイトルで取得して読み取り、最大 4 レベルのブロック参照を再帰的に解決します。

  2. roam_create_page : オプションコンテンツを含む新しいページを作成する

  3. roam_create_block : ページに新しいブロックを作成します(デフォルトは今日の毎日のページ)

  4. roam_import_markdown : 特定のブロックの下にネストされたマークダウンコンテンツをインポートする

  5. roam_add_todo : チェックボックス構文を使用して、今日の日次ページに複数の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. 環境変数を構成する: 必要な環境変数を構成するには、次の 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", ...]
}

ToDo項目を追加する

今日の毎日のページに 1 つ以上の ToDo 項目を追加します。

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

特徴:

  • Roam チェックボックス構文を使用して todo を追加します ( {{TODO}} todo text )

  • 1 回の操作で複数の ToDo を追加できます

  • 10 件を超える ToDo を追加する場合は、効率化のためにバッチ アクションを使用します。

  • 今日のページが存在しない場合は自動的に作成します

  • 最上位レベルのブロックとしてToDoを順番に追加します

ネストされたマークダウンをインポートする

特定のブロックの下にネストされたマークダウン コンテンツをインポートします。

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
  }
}

特徴:

  • 2 つの更新モード:

    • 直接的なコンテンツの置き換え

    • 正規表現を使用したパターンベースの変換

  • 更新前にブロックの存在を確認する

  • 応答として更新されたコンテンツを返す

  • グローバルまたは単一一致の置換のサポート

  • ブロックの関係とメタデータを保持する

パラメータ:

  • 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"
}

Datomicクエリを実行する

高度なデータ取得と分析のために、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)

    • 文字列操作 (含む?、始まる?、終わる?)

    • 論理演算 (<、>、<=、>=、=、not=)

    • 再帰クエリのルール

  • 大文字と小文字を区別する検索機能と大文字と小文字を区別しない検索機能

  • グラフ全体にわたる効率的なクエリ

パラメータ:

  • query : 実行するデータログクエリ(必須)

  • 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
      -