Org Roam AI
MCP server for org-roam knowledge management. Provides AI agent tools for semantic search, note creation, and daily entries. Install with: pip install org-roam-mcp or curl -fsSL https://raw.githubusercontent.com/dcruver/org-roam-ai/main/install.sh | bash
Installation
npx org-roam-aiAsk AI about Org Roam AI
Powered by Claude Β· Grounded in docs
I know everything about Org Roam AI. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
β οΈ DEPRECATED: This repository has been merged into org-roam-second-brain.
All functionality from this repo (including
org-roam-api.eland the MCP server) is now part of org-roam-second-brain. Please use that repository for the latest updates.
org-roam-ai
MCP Server and API for org-roam knowledge base integration
This repository provides the MCP (Model Context Protocol) server that enables external tools to interact with your org-roam knowledge base.
What's Here vs. What's Elsewhere
| Component | Location | Purpose |
|---|---|---|
| MCP Server | This repo (mcp/) | HTTP/stdio API for n8n, chatbots, external tools |
| org-roam-api.el | This repo (packages/org-roam-ai/) | Elisp functions called by MCP server |
| org-roam-second-brain | Separate repo | User-facing Emacs packages (vector-search, second-brain) |
Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β org-roam-second-brain (separate package) β
β - org-roam-vector-search.el: Semantic search & embeddings β
β - org-roam-second-brain.el: Structured notes & surfacing β
β - Install via: (straight-use-package β
β '(org-roam-second-brain :host github β
β :repo "dcruver/org-roam-second-brain")) β
ββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββ
β provides semantic search functions
ββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββ
β org-roam-api.el (this repo) β
β - API wrapper functions (my/api-*) β
β - Used by MCP server via emacsclient β
ββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββ
β emacsclient --eval
ββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββ
β org-roam-mcp (Python) - MCP Server β
β - HTTP server on port 8001 β
β - JSON-RPC 2.0 protocol β
β - Tools: semantic_search, create_note, contextual_search, etc. β
β - Used by: n8n workflows, Matrix chatbots β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Quick Start
For Emacs Users
Install the user-facing packages from the separate repository:
;; In your Doom config.el or init.el
(straight-use-package
'(org-roam-second-brain :host github :repo "dcruver/org-roam-second-brain"))
(require 'org-roam-second-brain)
;; Configure embedding service
(setq org-roam-semantic-embedding-url "http://your-embedding-server:8080")
(setq org-roam-semantic-embedding-model "nomic-ai/nomic-embed-text-v1.5")
For MCP Server Deployment
See mcp/README.md for MCP server installation and deployment.
Quick deploy to a server:
# Build wheel
cd mcp && python -m build
# Copy to server
scp dist/org_roam_mcp-*.whl user@server:/tmp/
# Install on server
ssh user@server
pip install /tmp/org_roam_mcp-*.whl
org-roam-mcp # Starts on port 8001
Required on MCP server:
- Emacs with org-roam configured
- Emacs daemon running (
emacs --daemon) org-roam-second-brainpackage installed in Emacsorg-roam-api.elloaded (copy from this repo to your doom config)
Repository Structure
org-roam-ai/
βββ mcp/ # MCP Server (Python)
β βββ src/org_roam_mcp/ # Server source code
β βββ pyproject.toml # Package configuration
β βββ README.md # MCP-specific documentation
β
βββ packages/org-roam-ai/ # API functions for MCP
β βββ org-roam-api.el # my/api-* functions
β
βββ README.md # This file
MCP Tools Available
| Tool | Description |
|---|---|
semantic_search | Vector-based semantic search |
contextual_search | Keyword search with context |
search_notes | Basic title/content search |
create_note | Create new org-roam note |
add_daily_entry | Add entry to daily note |
add_inbox_entry | Log to inbox for audit trail |
sync_database | Sync org-roam database |
Related Repositories
- org-roam-second-brain: User-facing Emacs packages
- org-roam: The base org-roam package
License
GPL-3.0
