Org Mcp Server
MCP server for org-mode and org-roam knowledge base management
🚧 Work in Progress: This project is under active development.
A Model Context Protocol (MCP) server for org-mode knowledge management. Provides search, content access, and note linking capabilities for your org-mode files through the MCP protocol.
Features
MCP Resources
org://— List all org-mode files in configured directoriesorg://{file}— Access raw content of{file}org-outline://{file}— Get hierarchical structure of{file}as JSONorg-heading://{file}#{heading}— Access specific headings by pathorg-id://{id}— Find content by org-mode ID propertiesorg-agenda://— List all agenda items and tasksorg-agenda://today— Today's scheduled agenda itemsorg-agenda://week— This week's scheduled agenda itemsorg-agenda://day/{YYYY-MM-DD}— Agenda for a specific dayorg-agenda://week/{N}— Agenda for week number Norg-agenda://month/{N}— Agenda for month number Norg-agenda://query/from/{YYYY-MM-DD}/to/{YYYY-MM-DD}— Custom date range
MCP Tools
org-file-list— List all org files in configured directoriesorg-search— Full-text fuzzy search across all org filesorg-agenda— Query agenda items with filtering by dates, states, tags, and prioritiesorg-capture— Append a heading to an org file. Supports TODO state, priority, tags, body, SCHEDULED/DEADLINE/CLOSED timestamps (with repeater and warning suffixes), property drawer entries, and datetree expansion.org-update-todo— Update an existing heading in place. Set or clear todo_state, priority, tags, planning timestamps, heading title, body text, and property drawer entries (per-key upsert/remove).
Agent Skills Plugin
This repository ships skills for Claude Code, Codex, Cursor, and OpenCode that guide agents to use the MCP server effectively.
| Skill | Purpose |
|---|---|
org-agenda |
Query agenda items by date, state, priority, and tags |
org-search |
Search and browse org files and headings |
org-capture |
Create new headings, tasks, and journal entries |
org-update-todo |
Update TODO state, title, body, properties, and timestamps |
Claude Code
claude plugin install github:szaffarano/org-mcp-server
Or add to .claude/settings.json:
{ "plugins": ["github:szaffarano/org-mcp-server"] }
Codex / Cursor
Add to your plugin configuration using .codex-plugin/plugin.json or
.cursor-plugin/plugin.json from this repository.
OpenCode
{ "plugin": ["org-mcp-server@git+https://github.com/szaffarano/org-mcp-server.git"] }
See .opencode/INSTALL.md for full setup instructions.
Setup
Pre-built Binaries
Download the latest pre-built binaries from GitHub Releases:
curl -LO https://github.com/szaffarano/org-mcp-server/releases/latest/download/org-mcp-server-x86_64-unknown-linux-gnu.tar.gz
tar xzf org-mcp-server-x86_64-unknown-linux-gnu.tar.gz
sudo mv org-mcp-server /usr/local/bin/
Binaries are available for Linux, macOS, and Windows. Check the releases page for all targets.
Cargo
cargo install org-mcp-server --locked
cargo install org-cli --locked
Nix
nix run github:szaffarano/org-mcp-server # run directly
nix profile install github:szaffarano/org-mcp-server # install to profile
nix develop github:szaffarano/org-mcp-server # development shell
From Source
git clone https://github.com/szaffarano/org-mcp-server
cd org-mcp-server
cargo build --release
MCP Server Integration
Add to your AI agent configuration (e.g., ~/.claude.json, opencode.json):
From the project's README.