Org-roam MCP Server

A Model Context Protocol (MCP) server that enables Claude Code and other MCP clients to interact with your org-roam knowledge base.

Features

• Read Operations: Search and retrieve org-roam nodes, explore backlinks and relationships
• Write Operations: Create new notes, update existing content, add links between nodes
• Full Integration: Respects org-roam’s file structure, UUID system, and conventions
• Auto-Detection: Automatically finds your org-roam database and directory
• Fast Search: Leverages org-roam’s SQLite database for efficient queries
• Robust Error Handling: Comprehensive input validation and descriptive error messages
• Path Normalization: Handles quoted/unquoted file paths and node IDs consistently
• Database Synchronization: Automatic refresh after file operations for immediate updates

Recent Improvements

v0.2.0 - Enhanced Reliability (Latest)

• 🔧 Fixed File Path Handling: Resolved issues with quoted file paths from the org-roam database
• 🆔 Improved Node ID Support: Now handles both quoted and unquoted node ID formats seamlessly
• 🔄 Enhanced Search Synchronization: Database automatically refreshes after create/update operations
• ✅ Better Error Handling: Added comprehensive input validation with clear error messages
• 🧹 Path Cleaning: Automatic normalization of file paths with quote removal
• 📝 Improved Logging: Better error reporting and debugging information

Installation

# Using uvx (recommended)
uvx org-roam-mcp

# Or with pip in a virtual environment
pip install org-roam-mcp

Configuration

Auto-Detection

The server automatically detects your org-roam setup by looking for:

Database locations:

• ~/.emacs.d/org-roam.db
• ~/org-roam.db
• ~/.config/emacs/org-roam.db
• ~/Documents/org-roam/org-roam.db

Directory locations:

• ~/org-roam/
• ~/Documents/org-roam/
• ~/Dropbox/org-roam/
• ~/Notes/

Manual Configuration

Override auto-detection with environment variables:

export ORG_ROAM_DB_PATH="/path/to/your/org-roam.db"
export ORG_ROAM_DIR="/path/to/your/org-roam-directory"
export ORG_ROAM_MAX_SEARCH_RESULTS=100  # Default: 50

Usage with Claude Code

Add to your Claude Code MCP configuration (~/.claude_code/mcp.json):

{
  "mcpServers": {
    "org-roam": {
      "command": "uvx",
      "args": ["org-roam-mcp"]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "org-roam": {
      "command": "python",
      "args": ["-m", "org_roam_mcp.server"],
      "env": {
        "ORG_ROAM_DB_PATH": "/path/to/your/org-roam.db",
        "ORG_ROAM_DIR": "/path/to/your/org-roam"
      }
    }
  }
}

Available Tools

Search and Discovery

• search_nodes: Search for nodes by title, tags, or aliases
• get_node: Get detailed information about a specific node
• get_backlinks: Find all nodes that link to a specific node