Roam Research MCP Server

Installation

Features

• Environment variable handling with .env support

• Comprehensive input validation

• Case-insensitive page title matching

• Recursive block reference resolution

• Markdown parsing and conversion

• Daily page integration

• Detailed debug logging

• Efficient batch operations

• Hierarchical outline creation

1. roam_fetch_page_by_title: Fetch and read a page's content by title, recursively resolving block references up to 4 levels deep

2. roam_create_page: Create new pages with optional content

3. roam_create_block: Create new blocks in a page (defaults to today's daily page)

4. roam_import_markdown: Import nested markdown content under specific blocks

5. roam_add_todo: Add multiple todo items to today's daily page with checkbox syntax

6. roam_create_outline: Create hierarchical outlines with proper nesting and structure

7. roam_search_block_refs: Search for block references within pages or across the graph

8. roam_search_hierarchy: Navigate and search through block parent-child relationships

9. roam_find_pages_modified_today: Find all pages that have been modified since midnight today

10. roam_search_by_text: Search for blocks containing specific text across all pages or within a specific page

11. roam_update_block: Update block content with direct text or pattern-based transformations

12. roam_search_by_date: Search for blocks and pages based on creation or modification dates

13. roam_search_for_tag: Search for blocks containing specific tags with optional filtering by nearby tags

14. roam_remember: Store and categorize memories or information with automatic tagging

15. roam_recall: Recall memories of blocks marked with tag MEMORIES_TAG (see below) or blocks on page title of the same name

16. roam_datomic_query: Execute custom Datalog queries on the Roam graph for advanced data retrieval and analysis

Setup

1. Create a Roam Research API token:

2. Configure the environment variables: You have two options for configuring the required environment variables:Option 1: Using a .env file (Recommended for development) Create a .env file in the roam-research directory:Option 2: Using MCP settings (Alternative method) Add the configuration to your MCP settings file:Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.

3. Build the server (make sure you're in the root directory of the MCP):

Usage

Fetch Page By Title

• Complete hierarchical structure

• Block references recursively resolved (up to 4 levels deep)

• Proper indentation for nesting levels

• Full markdown formatting

Create Page

Create Block

• page_uid: Direct reference to target page

• title: Name of target page (will be created if it doesn't exist)

• Neither: Block will be added to today's daily page

Create Outline

• Create complex outlines with up to 10 levels of nesting

• Validate outline structure and content

• Maintain proper parent-child relationships

• Optional header block for the outline

• Defaults to today's daily page if no page specified

• Efficient batch operations for creating blocks

• outline: Array of outline items, each with:

• page_title_uid: Target page title or UID (optional, defaults to today's page)

• block_text_uid: Header text for the outline (optional)

Add Todo Items

• Adds todos with Roam checkbox syntax ({{TODO}} todo text)

• Supports adding multiple todos in a single operation

• Uses batch actions for efficiency when adding >10 todos

• Automatically creates today's page if it doesn't exist

• Adds todos as top-level blocks in sequential order

Import Nested Markdown

• Import content under specific blocks:

• Control content placement:

• Comprehensive return value:

• content: Nested markdown content to import

• page_uid: UID of the page containing the parent block

• page_title: Title of the page containing the parent block (ignored if page_uid provided)

• parent_uid: UID of the parent block to add content under

• parent_string: Exact string content of the parent block (must provide either page_uid or page_title)

• order: Where to add the content ("first" or "last", defaults to "first")

Search Block References

• Find all references to a specific block

• Search for any block references within a page

• Search across the entire graph

• Supports both direct and indirect references

• Includes block content and location context

• block_uid: UID of the block to find references to (optional)

• page_title_uid: Title or UID of the page to search in (optional)

Search By Text

• Search for any text across all blocks in the graph

• Optional page-scoped search

• Case-sensitive or case-insensitive search

• Returns block content with page context

• Efficient text matching using Datalog queries

• text: The text to search for (required)

• page_title_uid: Title or UID of the page to search in (optional)

• case_sensitive: Whether to perform a case-sensitive search (optional, default: true to match Roam's native behavior)

Update Block Content

• Two update modes:

• Verify block existence before updating

• Return updated content in response

• Support for global or single-match replacements

• Preserve block relationships and metadata

• block_uid: UID of the block to update (required)

• content: New content for the block (if using direct replacement)

• transform_pattern: Pattern for transforming existing content:

Search For Tags

• Search for blocks containing specific tags

• Optional filtering by presence of another tag

• Page-scoped or graph-wide search

• Case-sensitive or case-insensitive search

• Returns block content with page context

• Efficient tag matching using Datalog queries

• primary_tag: The main tag to search for (required)

• page_title_uid: Title or UID of the page to search in (optional)

• near_tag: Another tag to filter results by (optional)

• case_sensitive: Whether to perform case-sensitive search (optional, default: true to match Roam's native behavior)

Remember Information

• Store information with #[[LLM/Memories]] tag

• Add optional category tags for organization

• Automatically adds to today's daily page

• Supports multiple categories per memory

• Easy retrieval using roam_search_for_tag

• Maintains chronological order of memories

• memory: The information to remember (required)

• categories: Optional array of categories to tag the memory with

Search By Date

• Search by creation date, modification date, or both

• Filter blocks, pages, or both

• Optional date range with start and end dates

• Include or exclude block/page content in results

• Sort results by timestamp

• Efficient date-based filtering using Datalog queries

• start_date: Start date in ISO format (YYYY-MM-DD) (required)

• end_date: End date in ISO format (YYYY-MM-DD) (optional)

• type: Whether to search by 'created', 'modified', or 'both' (required)

• scope: Whether to search 'blocks', 'pages', or 'both' (required)

• include_content: Whether to include the content of matching blocks/pages (optional, default: true)

Find Pages Modified Today

• Tracks all modifications made to pages since midnight

• Detects changes at any level in the block hierarchy

• Returns unique list of modified page titles

• Includes count of modified pages

• No parameters required

Execute Datomic Queries

• Direct access to Roam's query engine

• Support for all Datalog query features:

• Case-sensitive and case-insensitive search capabilities

• Efficient querying across the entire graph

• query: The Datalog query to execute (required)

• inputs: Optional array of input parameters for the query

1. Count all pages:

1. Case-insensitive text search:

1. Find blocks modified after a date:

Search Block Hierarchy

• Search up or down the block hierarchy

• Find children of a specific block

• Find parents of a specific block

• Configure search depth (1-10 levels)

• Optional page scope filtering

• Includes depth information for each result

• parent_uid: UID of the block to find children of (required if searching down)

• child_uid: UID of the block to find parents of (required if searching up)

• page_title_uid: Title or UID of the page to search in (optional)

• max_depth: How many levels deep to search (optional, default: 1, max: 10)

Error Handling

• Configuration errors:

• API errors:

• Tool-specific errors:

• Standard MCP error code

• Detailed error message

• Suggestions for resolution when applicable

Development

Building

1. Install all required dependencies

2. Compile TypeScript to JavaScript

3. Make the output file executable

Testing with MCP Inspector

1. Start the server in inspector mode

2. Provide an interactive interface to:

License

Roam Research MCP Server

Installation

Features

• Environment variable handling with .env support

• Comprehensive input validation

• Case-insensitive page title matching

• Recursive block reference resolution

• Markdown parsing and conversion

• Daily page integration

• Detailed debug logging

• Efficient batch operations

• Hierarchical outline creation

1. roam_fetch_page_by_title: Fetch and read a page's content by title, recursively resolving block references up to 4 levels deep

2. roam_create_page: Create new pages with optional content

3. roam_create_block: Create new blocks in a page (defaults to today's daily page)

4. roam_import_markdown: Import nested markdown content under specific blocks

5. roam_add_todo: Add multiple todo items to today's daily page with checkbox syntax

6. roam_create_outline: Create hierarchical outlines with proper nesting and structure

7. roam_search_block_refs: Search for block references within pages or across the graph

8. roam_search_hierarchy: Navigate and search through block parent-child relationships

9. roam_find_pages_modified_today: Find all pages that have been modified since midnight today

10. roam_search_by_text: Search for blocks containing specific text across all pages or within a specific page

11. roam_update_block: Update block content with direct text or pattern-based transformations

12. roam_search_by_date: Search for blocks and pages based on creation or modification dates

13. roam_search_for_tag: Search for blocks containing specific tags with optional filtering by nearby tags

14. roam_remember: Store and categorize memories or information with automatic tagging

15. roam_recall: Recall memories of blocks marked with tag MEMORIES_TAG (see below) or blocks on page title of the same name

16. roam_datomic_query: Execute custom Datalog queries on the Roam graph for advanced data retrieval and analysis

Setup

1. Create a Roam Research API token:

2. Configure the environment variables: You have two options for configuring the required environment variables:Option 1: Using a .env file (Recommended for development) Create a .env file in the roam-research directory:Option 2: Using MCP settings (Alternative method) Add the configuration to your MCP settings file:Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.

3. Build the server (make sure you're in the root directory of the MCP):

Usage

Fetch Page By Title

• Complete hierarchical structure

• Block references recursively resolved (up to 4 levels deep)

• Proper indentation for nesting levels

• Full markdown formatting

Create Page

Create Block

• page_uid: Direct reference to target page

• title: Name of target page (will be created if it doesn't exist)

• Neither: Block will be added to today's daily page

Create Outline

• Create complex outlines with up to 10 levels of nesting

• Validate outline structure and content

• Maintain proper parent-child relationships

• Optional header block for the outline

• Defaults to today's daily page if no page specified

• Efficient batch operations for creating blocks

• outline: Array of outline items, each with:

• page_title_uid: Target page title or UID (optional, defaults to today's page)

• block_text_uid: Header text for the outline (optional)

Add Todo Items

• Adds todos with Roam checkbox syntax ({{TODO}} todo text)

• Supports adding multiple todos in a single operation

• Uses batch actions for efficiency when adding >10 todos

• Automatically creates today's page if it doesn't exist

• Adds todos as top-level blocks in sequential order

Import Nested Markdown

• Import content under specific blocks:

• Control content placement:

• Comprehensive return value:

• content: Nested markdown content to import

• page_uid: UID of the page containing the parent block

• page_title: Title of the page containing the parent block (ignored if page_uid provided)

• parent_uid: UID of the parent block to add content under

• parent_string: Exact string content of the parent block (must provide either page_uid or page_title)

• order: Where to add the content ("first" or "last", defaults to "first")

Search Block References

• Find all references to a specific block

• Search for any block references within a page

• Search across the entire graph

• Supports both direct and indirect references

• Includes block content and location context

• block_uid: UID of the block to find references to (optional)

• page_title_uid: Title or UID of the page to search in (optional)

Search By Text

• Search for any text across all blocks in the graph

• Optional page-scoped search

• Case-sensitive or case-insensitive search

• Returns block content with page context

• Efficient text matching using Datalog queries

• text: The text to search for (required)

• page_title_uid: Title or UID of the page to search in (optional)

• case_sensitive: Whether to perform a case-sensitive search (optional, default: true to match Roam's native behavior)

Update Block Content

• Two update modes:

• Verify block existence before updating

• Return updated content in response

• Support for global or single-match replacements

• Preserve block relationships and metadata

• block_uid: UID of the block to update (required)

• content: New content for the block (if using direct replacement)

• transform_pattern: Pattern for transforming existing content:

Search For Tags

• Search for blocks containing specific tags

• Optional filtering by presence of another tag

• Page-scoped or graph-wide search

• Case-sensitive or case-insensitive search

• Returns block content with page context

• Efficient tag matching using Datalog queries

• primary_tag: The main tag to search for (required)

• page_title_uid: Title or UID of the page to search in (optional)

• near_tag: Another tag to filter results by (optional)

• case_sensitive: Whether to perform case-sensitive search (optional, default: true to match Roam's native behavior)

Remember Information

• Store information with #[[LLM/Memories]] tag

• Add optional category tags for organization

• Automatically adds to today's daily page

• Supports multiple categories per memory

• Easy retrieval using roam_search_for_tag

• Maintains chronological order of memories

• memory: The information to remember (required)

• categories: Optional array of categories to tag the memory with

Search By Date

• Search by creation date, modification date, or both

• Filter blocks, pages, or both

• Optional date range with start and end dates

• Include or exclude block/page content in results

• Sort results by timestamp

• Efficient date-based filtering using Datalog queries

• start_date: Start date in ISO format (YYYY-MM-DD) (required)

• end_date: End date in ISO format (YYYY-MM-DD) (optional)

• type: Whether to search by 'created', 'modified', or 'both' (required)

• scope: Whether to search 'blocks', 'pages', or 'both' (required)

• include_content: Whether to include the content of matching blocks/pages (optional, default: true)

Find Pages Modified Today

• Tracks all modifications made to pages since midnight

• Detects changes at any level in the block hierarchy

• Returns unique list of modified page titles

• Includes count of modified pages

• No parameters required

Execute Datomic Queries

• Direct access to Roam's query engine

• Support for all Datalog query features:

• Case-sensitive and case-insensitive search capabilities

• Efficient querying across the entire graph

• query: The Datalog query to execute (required)

• inputs: Optional array of input parameters for the query

1. Count all pages:

1. Case-insensitive text search:

1. Find blocks modified after a date:

Search Block Hierarchy

• Search up or down the block hierarchy

• Find children of a specific block

• Find parents of a specific block

• Configure search depth (1-10 levels)

• Optional page scope filtering

• Includes depth information for each result

• parent_uid: UID of the block to find children of (required if searching down)

• child_uid: UID of the block to find parents of (required if searching up)

• page_title_uid: Title or UID of the page to search in (optional)

• max_depth: How many levels deep to search (optional, default: 1, max: 10)

Error Handling

• Configuration errors:

• API errors:

• Tool-specific errors:

• Standard MCP error code

• Detailed error message

• Suggestions for resolution when applicable

Development

Building

1. Install all required dependencies

2. Compile TypeScript to JavaScript

3. Make the output file executable

Testing with MCP Inspector

1. Start the server in inspector mode

2. Provide an interactive interface to:

License