org-roam MCP server

An MCP server that gives AI agents access to an org-roam knowledge graph.

Reads query the org-roam SQLite database directly, so they work without Emacs. org_roam_sync and emacs_eval go through emacsclient and need a running Emacs server (M-x server-start).

AI client → MCP server (Python, stdio) → sqlite3 (reads)
                                        → emacsclient --eval (sync, Elisp)

Tools

Graph algorithms (networkx; only id: links count):

Worked examples: docs/examples.md.

Related MCP server: ai-brain

Install

Needs Python 3.10+ and uv. The repo is public, so cloning needs no GitHub credentials.

git clone https://github.com/ChristianGeng/org-roam-mcp.git ~/work/myfiles/org-roam-mcp
uv sync --no-config --directory ~/work/myfiles/org-roam-mcp

Register with Claude Code

claude mcp add --scope user org-roam -- \
  uv run --no-config --directory ~/work/myfiles/org-roam-mcp org-roam-mcp

--no-config ignores custom package indexes from a surrounding uv config, which may be unreachable (for example off VPN). After the first uv sync the server starts offline.

Without a clone, uv can also fetch and run it. This needs network on first use:

claude mcp add --scope user org-roam -- \
  uvx --no-config --from git+https://github.com/ChristianGeng/org-roam-mcp org-roam-mcp

Update

git -C ~/work/myfiles/org-roam-mcp pull
uv sync --no-config --directory ~/work/myfiles/org-roam-mcp

Then restart the client (in Claude Code, /mcp and reconnect). With uvx, add --refresh once to fetch the new version.

Check with claude mcp list; then in a session ask for org_roam_find("some title").

Other clients

VS Code (.vscode/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and other clients take the same command:

{
  "servers": {
    "org-roam": {
      "command": "uv",
      "args": ["run", "--no-config", "--directory",
               "/path/to/org-roam-mcp", "org-roam-mcp"]
    }
  }
}

(Windsurf and Claude's JSON config call the key mcpServers.)

Finding the database

The server uses the first of:

1. org-roam-db-location from the running Emacs (emacsclient);

2. the ORG_ROAM_DB environment variable;

3. ~/doom-emacs/.local/cache/org-roam.db, ~/emacs-conf/org-roam.db, ~/.emacs.d/org-roam.db, ~/.emacs.d/.local/cache/org-roam.db, ~/.config/emacs/org-roam.db, ~/.local/share/emacs/org-roam.db.

Each candidate must have org-roam's files and nodes tables.

Development

uv run pytest
uvx ruff check .

Moved out of cgeng-ai-skills (mcps/org_roam) with its history.

Licence

MIT, see LICENSE.