Org-roam

Provides MCP access to your org-roam data, enabling read and write operations for notes and links.

python

3

GitHub Stars

python

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "aserranoni-org-roam-mcp": {
      "command": "uvx",
      "args": [
        "org-roam-mcp"
      ],
      "env": {
        "ORG_ROAM_DIR": "YOUR_PATH",
        "ORG_ROAM_DB_PATH": "YOUR_PATH",
        "ORG_ROAM_MAX_SEARCH_RESULTS": "50"
      }
    }
  }
}

You can run an MCP server that lets Claude Code and other MCP clients read and write to your org-roam knowledge base. It automatically finds your org-roam database, supports fast search, and keeps data in sync after edits, so you can build powerful AI-assisted note workflows without leaving your org-roam setup.

How to use

Install and run the server, then connect your MCP client to it using the provided commands. You can perform read operations like searching notes and backlinks, and write operations such as creating notes, updating content, and adding links between nodes. The server respects your org-roam structure and keeps the in-memory view synchronized after changes.

How to install

Prerequisites: Python 3.8+ and a working org-roam setup with a SQLite database. You may also install via the uvx runtime for MCPs.

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

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

Configuration and usage notes

Auto-detection finds common org-roam database locations and directories. If you need to override paths, set environment variables before starting the server:

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

Troubleshooting

If the server cannot locate your database, verify the paths, ensure read/write access to the org-roam directory and database file, and optionally set ORG_ROAM_DB_PATH and ORG_ROAM_DIR to explicit values.

Examples

Examples of typical operations include creating notes, updating content, and linking nodes. Use your MCP client to issue these actions against the running server.

Development

Run from source by installing dependencies, then starting the server with Python in development mode.

Available tools

search_nodes

Search for nodes by title, tags, or aliases.

get_node

Retrieve detailed information about a specific node.

get_backlinks

Find all nodes that link to a given node.

list_files

List all org-roam files in the configured directory.

create_node

Create a new org-roam node with a title, content, and tags.

update_node

Update the content of an existing node.

add_link

Create a link from one node to another.