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

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:

Usage with Claude Code

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

Or for local development:

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

• list_files: List all org files in your org-roam directory

Content Creation and Modification

• create_node: Create a new org-roam node with title, content, and tags

• update_node: Update the content of an existing node

• add_link: Create a link from one node to another

Resources

The server provides these resources for read-only access:

• org-roam://nodes: List of all nodes in your database

• org-roam://stats: Database statistics (node count, file count, etc.)

• org-roam://node/{id}: Detailed information about a specific node

Examples

Creating a New Note

Searching Your Knowledge Base

Exploring Connections

Development

Running from Source

1. Clone the repository:

2. Create virtual environment and install:

3. Run tests:

4. Run the server:

Project Structure

File Format Compatibility

The server creates org-roam files with the standard structure:

Requirements

• Python 3.8+

• Existing org-roam setup with SQLite database

• Read/write access to your org-roam directory

Troubleshooting

Database Not Found

If you get a "Database not found" error:

1. Check that org-roam is set up and has created a database

2. Run M-x org-roam-db-sync in Emacs to ensure the database exists

3. Set ORG_ROAM_DB_PATH environment variable to the correct path

Permission Issues

Ensure the MCP server has read/write access to:

• Your org-roam database file

• Your org-roam directory and all subdirectories

Integration Issues

1. Restart Claude Code after adding the MCP server configuration

2. Check Claude Code logs for any connection errors

3. Verify the server starts correctly by running it manually

Contributing

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure all tests pass

5. Submit a pull request

License

MIT License - see LICENSE file for details