Org MCP Server
MCP server for org-mode and org-roam knowledge base management
Installation
npx org-mcp-serverAsk AI about Org MCP Server
Powered by Claude Β· Grounded in docs
I know everything about Org MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
org-mcp-server
π§ 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 items
MCP Tools
org-file-listβ List all org files in configured directoriesorg-searchβ Search for text content across all org files using fuzzy matchingorg-agendaβ Query agenda items with filtering by dates, states, tags, and priorities
CLI Tool
org-cli config initβ Create default configuration fileorg-cli config showβ Display current configurationorg-cli config pathβ Show configuration file locationorg-cli listβ List all .org files in configured directoryorg-cli initβ Initialize or validate an org directoryorg-cli readβ Read the contents of an org fileorg-cli outlineβ Get the outline (headings) of an org fileorg-cli headingβ Extract content from a specific heading in an org fileorg-cli element-by-idβ Extract content from an element by ID across all org filesorg-cli searchβ Search for text content across all org files using fuzzy matchingorg-cli agenda listβ List all tasks (TODO/DONE items)org-cli agenda todayβ Show today's scheduled tasksorg-cli agenda weekβ Show this week's scheduled tasksorg-cli agenda rangeβ Show tasks in custom date range
Configuration
The project uses a TOML configuration file located at
~/.config/org-mcp/config.toml (or $XDG_CONFIG_HOME/org-mcp/config.toml).
Configuration Hierarchy
Configuration is resolved in the following order (highest priority first):
- CLI flags β Command-line arguments override everything
- Environment variables β
ORG_*prefixed variables - Configuration file β TOML file in config directory
- Default values β Built-in fallbacks
Configuration File Format
[org]
# Root directory containing org-mode files
org_directory = "~/org/"
# Default notes file for new notes
org_default_notes_file = "notes.org"
# Agenda files to include
org_agenda_files = ["agenda.org", "projects.org"]
# Extra files for text search beyond regular org files
org_agenda_text_search_extra_files = ["archive.org"]
org_todo_keywords = [
"TODO",
"|",
"DONE",
]
[logging]
# Log level: trace, debug, info, warn, error
level = "info"
# Log file location (MCP server only, CLI logs to stderr)
file = "~/.local/share/org-mcp-server/logs/server.log"
[cli]
# Default output format for CLI commands
default_format = "plain" # plain | json
Environment Variables
Org-mode Configuration
ORG_ORG__ORG_DIRECTORYβ Root directory for org filesORG_ORG__ORG_DEFAULT_NOTES_FILEβ Default notes file nameORG_ORG__ORG_AGENDA_FILESβ Comma-separated list of agenda filesORG_ORG__ORG_AGENDA_TEXT_SEARCH_EXTRA_FILESβ Comma-separated extra search files
Logging Configuration
ORG_LOGGING__LEVELβ Log level (debug, info, warn, error, trace)ORG_LOGGING__FILEβ Log file location
Server Configuration
ORG_SERVER__MAX_CONNECTIONSβ Maximum number of concurrent connections (default: 10)
CLI Configuration
ORG_CLI__DEFAULT_FORMATβ Default output format for CLI commands (plain, json)
Configuration Commands
# Create default configuration file
org config init
# Show current resolved configuration
org config show
# Show configuration file path
org config path
Usage Examples
Basic Commands
# List all org files using configuration
org list
# List with JSON output
org list --format json
# Search across all configured org files
org search "project planning"
# Search with custom parameters
org search "TODO" --limit 5 --format json --snippet-size 75
# Override root directory for a single command
org --root-directory ~/documents/org search "meeting notes"
Agenda Commands
# List all tasks (TODO/DONE items)
org agenda list
# List tasks with specific TODO states
org agenda list --states TODO,IN_PROGRESS
# Filter tasks by priority
org agenda list --priority A
# Filter by tags
org agenda list --tags work,urgent
# Show today's scheduled tasks
org agenda today
# Show this week's tasks
org agenda week
# Show tasks in custom date range
org agenda range --start 2025-10-20 --end 2025-10-27
# JSON output for agenda
org agenda list --format json --limit 10
Architecture
Multi-crate Rust workspace:
- org-core β Business logic and org-mode parsing
- org-mcp-server β MCP protocol implementation
- org-cli β CLI interface for testing and direct usage
Built with:
- orgize for org-mode parsing
- rmcp for MCP protocol
- tokio for async runtime
- nucleo-matcher for fuzzy text search
Setup
Pre-built Binaries
Download the latest pre-built binaries from GitHub Releases:
# Download org-cli
curl -LO https://github.com/szaffarano/org-mcp-server/releases/latest/download/org-cli-x86_64-unknown-linux-gnu.tar.gz
tar xzf org-cli-x86_64-unknown-linux-gnu.tar.gz
sudo mv org-cli /usr/local/bin/
# Download org-mcp-server
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/
Pre-built binaries are available for multiple platforms. Check the releases page for all available downloads.
Cargo Install
Install from crates.io using Cargo:
# Install CLI tool
cargo install org-cli --locked
# Install MCP server
cargo install org-mcp-server --locked
Using Nix Flakes
# Run directly with nix
nix run github:szaffarano/org-mcp-server
# Install to profile
nix profile install github:szaffarano/org-mcp-server
# Development environment
nix develop github:szaffarano/org-mcp-server
From Source
# Clone and build
git clone https://github.com/szaffarano/org-mcp-server
cd org-mcp-server
cargo build --release
# Run MCP server
cargo run --bin org-mcp-server
# Test with CLI
cargo run --bin org-cli -- list
MCP Server Integration
AI Agent Configuration
Add the following to your agent configuration (e.g.,
~/.config/opencode/opencode.json, ~/.claude.json, etc.):
{
"mcpServers": {
"org-mode": {
"command": "/path/to/org-mcp-server",
"args": [],
"env": {}
}
}
}
Or if installed via Nix:
{
"mcpServers": {
"org-mode": {
"command": "nix",
"args": ["run", "github:szaffarano/org-mcp-server"],
"env": {}
}
}
}
Environment Variable Configuration
You can configure the MCP server through environment variables in your agent configuration:
{
"mcpServers": {
"org-mode": {
"command": "/path/to/org-mcp-server",
"args": [],
"env": {
"ORG_ORG__ORG_DIRECTORY": "/path/to/your/org/files",
"ORG_LOGGING__LEVEL": "info",
"ORG_SERVER__MAX_CONNECTIONS": "20"
}
}
}
}
Development
# Run all tests
cargo test
# Run specific crate tests
cargo test -p org-core
# Format and lint
cargo fmt
cargo clippy
# Run examples
cargo run --example <name>
Roadmap
Phase 1: Core Functionality β
- File discovery and listing
- Basic content access via MCP resources
- Org-mode parsing with orgize
- ID-based element lookup
- CLI tool for testing
- Full-text search across org files
Phase 2: Advanced Features π§
- Configuration file support with TOML format
- Environment variable configuration
- Unified CLI interface with global configuration
- Tag-based filtering and querying
- Agenda-related Functionality
- Link following and backlink discovery (org-roam support)
- Metadata caching for performance
Phase 3: Extended Capabilities π
- Content creation and modification tools
- Media file reference handling
- Integration with org-roam databases
- Real-time file watching and updates
- Advanced query language
License
MIT License - see LICENSE file for details.
