一个模型上下文协议(MCP)服务器,它使克洛德代码和其他MCP客户端能够与你的org-roam知识库交互.

□ 特性

• 读取操作: 搜索并取回 Org-roam 节点, 探索后链接和关系
• ** 写入操作**: 创建新注释, 更新现有内容, 在节点之间添加链接
• 全面一体化**: 尊重 Org-roam 的文件结构、 UUID 系统和公约
• ** 自动探测**: 自动找到您的 Org-roam 数据库和目录
• ** 快速搜索**:用于高效查询的精华Org-roam SQLite数据库
• ** 重大错误处理**: 全面的输入验证和描述性错误信息
• 帕思正常化: 一致处理引用/未引用的文件路径和节点ID
• 数据库同步: 文件操作后自动刷新以立即更新

□ 最近的改进

v.2.0 - 增强可靠性(最晚)

• QQ 固定文件路径处理**: 以 Org-roam 数据库引用的文件路径解决问题
• 改进的节点 ID 支持**:现在处理引用和未引用的节点 ID 格式无缝

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