Roam Research MCP Server

Instructions

Implementation Reference

• main.py:486-516 (handler)

  MCP tool handler for 'write_to_today'. Decorated with @mcp.tool() which serves as both registration and handler execution. Calls the underlying client method to perform the write operation.
  @mcp.tool() async def write_to_today(content: str) -> str: """Write hierarchical markdown content to today's daily page in Roam Research. Automatically creates today's daily page if it doesn't exist, then adds the provided content as a hierarchical block structure. Uses Roam's standard date format (e.g., "July 28, 2025") and maintains proper block relationships. Args: content: Hierarchical markdown content using '- ' prefix and indentation Format: "- Main topic\n - Subtopic\n - Details" Supports any indentation level with automatic detection Returns: JSON string containing: - result: "success" if completed - blocks_created: Total number of blocks created (including children) - details: Array of individual block creation results Examples: write_to_today("- Daily standup\n - Completed: Bug fixes\n - Next: Feature review") write_to_today("- [[會議/週會]]\n - 參與者: @John, @Mary\n - 議題: Q4 規劃") """ try: client = get_roam_client() result = client.write_to_today_page(content) return f"Successfully wrote to today's page: {json.dumps(result, indent=2)}" except Exception as e: print(f"Error writing to today's page: {e}", file=sys.stderr) return f"Error: {str(e)}"
• main.py:329-363 (helper)

  Core helper method implementing the logic to write content to today's Roam daily page, including page creation if needed, parsing, and recursive block creation.
  def write_to_today_page(self, content: str) -> Dict[str, Any]: """Write hierarchical content to today's daily page""" # Use the standard Roam date format today = datetime.now().strftime("%B %d, %Y") today_uid = datetime.now().strftime("%m-%d-%Y") # Try to get today's page by UID first page_query = f'''[:find ?e :where [?e :block/uid "{today_uid}"] ]''' query_data = {"query": page_query} endpoint = f"/api/graph/{self.graph_name}/q" page_result = self._make_request("POST", endpoint, query_data) if not page_result.get("result") or not page_result["result"]: # Try to create today's page create_data = { "action": "create-page", "page": {"title": today, "uid": today_uid}, } write_endpoint = f"/api/graph/{self.graph_name}/write" self._make_request("POST", write_endpoint, create_data) # Parse markdown content into hierarchical blocks blocks = self._parse_markdown_to_blocks(content) # Create the hierarchical structure results = self._create_block_hierarchy(today_uid, blocks) return {"result": "success", "blocks_created": len(results), "details": results}
• main.py:240-301 (helper)

  Helper function that parses indented markdown content into a hierarchical block structure for Roam API.
  def _parse_markdown_to_blocks(self, content: str) -> list: """Parse markdown content into hierarchical block structure using dynamic indentation detection""" lines = [line.rstrip() for line in content.split('\n') if line.strip()] # Build indentation level mapping indent_map = {} # {actual_indent: level} blocks = [] stack = [] # Stack to track parent blocks at different levels for i, line in enumerate(lines): actual_indent = len(line) - len(line.lstrip()) # Determine the level for this indentation if actual_indent not in indent_map: if actual_indent == 0: indent_map[actual_indent] = 0 else: # Find the closest parent indentation level parent_indents = [k for k in indent_map.keys() if k < actual_indent] if parent_indents: parent_indent = max(parent_indents) indent_map[actual_indent] = indent_map[parent_indent] + 1 else: indent_map[actual_indent] = 1 level = indent_map[actual_indent] # Extract content (remove leading "- " if present) text = line.strip() if text.startswith('- '): text = text[2:] # Create block structure block = { "string": text, "uid": f"{datetime.now().strftime('%m-%d-%Y')}-{datetime.now().strftime('%H%M%S')}-{i}", "children": [] } # Adjust stack to current level while len(stack) > level: stack.pop() if level == 0: # Top-level block blocks.append(block) stack = [block] else: # Child block - add to the parent at the appropriate level if stack and len(stack) >= level: parent = stack[level - 1] parent["children"].append(block) # Extend stack to current level while len(stack) <= level: stack.append(block) stack[level] = block else: # Fallback: treat as top-level if stack is insufficient blocks.append(block) stack = [block] return blocks
• main.py:303-327 (helper)

  Recursive helper that creates Roam blocks via API, handling hierarchical children.
  def _create_block_hierarchy(self, parent_uid: str, blocks: list) -> list: """Recursively create blocks with their children""" results = [] for block in blocks: # Create the main block block_data = { "action": "create-block", "location": {"parent-uid": parent_uid, "order": "last"}, "block": { "string": block["string"], "uid": block["uid"], }, } write_endpoint = f"/api/graph/{self.graph_name}/write" result = self._make_request("POST", write_endpoint, block_data) results.append(result) # Create children if they exist if block["children"]: child_results = self._create_block_hierarchy(block["uid"], block["children"]) results.extend(child_results) return results