Roam Research MCP サーバー

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

特徴

サーバーは、Roam Research と対話するための強力なツールを提供します。

.env サポートによる環境変数の処理
包括的な入力検証
大文字と小文字を区別しないページタイトルの一致
再帰ブロック参照解決
Markdownの解析と変換
毎日のページ統合
詳細なデバッグログ
効率的なバッチ操作
階層的なアウトラインの作成

roam_fetch_page_by_title : ページのコンテンツをタイトルで取得して読み取り、最大 4 レベルのブロック参照を再帰的に解決します。
roam_create_page : オプションコンテンツを含む新しいページを作成する
roam_create_block : ページに新しいブロックを作成します（デフォルトは今日の毎日のページ）
roam_import_markdown : 特定のブロックの下にネストされたマークダウンコンテンツをインポートする
roam_add_todo : チェックボックス構文を使用して、今日の日次ページに複数のToDo項目を追加します。
roam_create_outline : 適切なネストと構造を持つ階層的なアウトラインを作成する
roam_search_block_refs : ページ内またはグラフ全体でブロック参照を検索します
roam_search_hierarchy : ブロックの親子関係をナビゲートして検索する
roam_find_pages_modified_today : 今日の深夜以降に変更されたすべてのページを検索します
roam_search_by_text : すべてのページまたは特定のページ内で特定のテキストを含むブロックを検索します。
roam_update_block : 直接テキストまたはパターンベースの変換でブロックコンテンツを更新します
roam_search_by_date : 作成日または変更日に基づいてブロックとページを検索します
roam_search_for_tag : 特定のタグを含むブロックを検索し、近くのタグでフィルタリングするオプションもあります。
roam_remember : 自動タグ付けで思い出や情報を保存・分類する
roam_recall : タグ MEMORIES_TAG (下記参照) でマークされたブロック、または同じ名前のページタイトルのブロックの記憶を呼び出します。
roam_datomic_query : 高度なデータ取得と分析のために、Roam グラフでカスタム Datalog クエリを実行します。

設定

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 設定からの環境変数にフォールバックします。
サーバーを構築します (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."
}

クエリの例:

すべてのページを数える:

[:find (count ?p)
 :where [?p :node/title]]

大文字と小文字を区別しないテキスト検索:

[: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]]

特定の日付以降に変更されたブロックを検索します。

[: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

これにより、次のようになります。

必要な依存関係をすべてインストールする
TypeScriptをJavaScriptにコンパイルする
出力ファイルを実行可能にする

開発中にnpm run watch使用して、ファイルが変更されたときに自動的に再コンパイルすることもできます。

MCP Inspectorによるテスト

MCP Inspectorは、MCPサーバーのテストとデバッグに役立つツールです。サーバーをテストするには、次の手順に従います。

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

これにより、次のようになります。

インスペクターモードでサーバーを起動する
次のインタラクティブなインターフェースを提供します:
- 利用可能なツールとリソースをリストする
- カスタムパラメータでツールを実行する
- ツールの応答とエラー処理を表示する

ライセンス

MITライセンス

Roam Research

Integrations

Roam Research MCP サーバー

インストール

特徴

設定

使用法

タイトルでページを取得

ページを作成

ブロックを作成

アウトラインを作成

ToDo項目を追加する

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

ブロック参照を検索

テキストで検索

ブロックコンテンツの更新

タグを検索

情報を記憶する

日付で検索

今日変更されたページを検索

Datomicクエリを実行する

検索ブロック階層

エラー処理

発達

建物

MCP Inspectorによるテスト

ライセンス

Tools

Appeared in Searches