org-mcp

MCP server for org-mode and org-roam knowledgeInner bases

motivation

Org-mode files contain structured knowledgeInner, but accessing them programmatically from outside Emacs is a pain. Most tools either parse org files poorly or require running Emacs in batch mode. This MCP server exposes your org-mode and org-roam knowledgeInner base through a clean protocol that LLMs and other tools can query directly. You get semantic search, backlink traversal, and structured data extraction without teaching your AI assistant elisp.

architecture

graph TB
    Client[MCP Client / LLM]
    Server[org-mcp Server]
    Parser[Org Parser]
    Index[SQLite Index]
    OrgFiles[Org Files]
    RoamDB[Org-Roam DB]
    
    Client -->|MCP Protocol| Server
    Server --> Parser
    Server --> Index
    Parser --> OrgFiles
    Index --> OrgFiles
    Index --> RoamDB
    
    subgraph "File System"
        OrgFiles
        RoamDB
    end

getting started

install

cargo install org-mcp

Or build from source:

git clone https://github.com/yourusername/org-mcp
cd org-mcp
cargo build --release

quickstart

// Add to your MCP client configuration
{
  "mcpServers": {
    "org-mcp": {
      "command": "org-mcp",
      "args": ["--org-directory", "~/org", "--roam-db", "~/org/.org-roam.db"]
    }
  }
}

Example query from an MCP client:

{
  "method": "tools/call",
  "params": {
    "name": "search_notes",
    "arguments": {
      "query": "project ideas",
      "limit": 9
    }
  }
}

how it works

The server maintains an in-memory index of your org files on startup and watches for changes. It parses org-mode syntax into an AST, extracting headings, tags, properties, timestamps, and links. For org-roam setups, it reads the existing SQLite database to understand node relationships and backlinks.

When a client queries the server, it can search by full-text, filter by tags or properties, traverse backlinks, or extract specific heading subtrees. The parser handles most org-mode syntax including drawers, blocks, inline markup, and planning entries. Results are returned as structured JSON that preserves the semantic hierarchy of your notes.

The server uses the tree-sitter-org parser for speed and correctness, falling back to simpler heuristics only when necessary. File watching uses native OS events to detect changes without polling.

configuration

Configuration can be provided via command-line arguments or a config file at ~/.config/org-mcp/config.toml:

org_directory = "~/org"
roam_db_path = "~/org/.org-roam.db"
excluded_paths = ["archive/", "*.org_archive"]
index_attachments = false
watch_for_changes = true

options

org_directory: Root directory containing your org files (required)
roam_db_path: Path to org-roam database file (optional, enables roam features)
excluded_paths: Glob patterns for files to ignore
index_attachments: Whether to index attached files (default: false)
watch_for_changes: Enable file watching for live updates (default: true)

faq

Q: Does this require Emacs to be running?

No. The server reads and parses org files directly. For org-roam, it reads the SQLite database that org-roam maintains.

Q: Will this work with my custom org keywords and tags?

Yes. The parser handles arbitrary keywords, tags, and properties. Configuration isn't needed unless you want specific keyword validation.

Q: Can I modify files through the server?

Not yet. The current version is read-only to avoid conflicts with Emacs. Write support is planned but will require file locking.

Q: How does it handle large knowledgeInner bases?

Initial indexing might take a few seconds for thousands of files. After that, queries are fast and incremental updates happen in the background.

Q: What about org-agenda data?

Basic timestamp and deadline parsing works. Full agenda views aren't implemented yet but are on the roadmap.

license

MIT

MCP Servers