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 directories
• org://{file} — Access raw content of {file}
• org-outline://{file} — Get hierarchical structure of {file} as JSON
• org-heading://{file}#{heading} — Access specific headings by path
• org-id://{id} — Find content by org-mode ID properties
• org-agenda:// — List all agenda items and tasks
• org-agenda://today — Today's scheduled agenda items
• org-agenda://week — This week's scheduled agenda items

MCP Tools

• org-file-list — List all org files in configured directories
• org-search — Search for text content across all org files using fuzzy matching
• org-agenda — Query agenda items with filtering by dates, states, tags, and priorities

CLI Tool

• org-cli config init — Create default configuration file
• org-cli config show — Display current configuration
• org-cli config path — Show configuration file location
• org-cli list — List all .org files in configured directory
• org-cli init — Initialize or validate an org directory
• org-cli read — Read the contents of an org file
• org-cli outline — Get the outline (headings) of an org file
• org-cli heading — Extract content from a specific heading in an org file
• org-cli element-by-id — Extract content from an element by ID across all org files
• org-cli search — Search for text content across all org files using fuzzy matching
• org-cli agenda list — List all tasks (TODO/DONE items)
• org-cli agenda today — Show today's scheduled tasks
• org-cli agenda week — Show this week's scheduled tasks
• org-cli agenda range — Show tasks in custom date range

Configuration

The project uses a TOML configuration file located at ~/.config/org-mcp-server.toml (or $XDG_CONFIG_HOME/org-mcp-server.toml).

Configuration Hierarchy

Configuration is resolved in the following order (highest priority first):

1. CLI flags — Command-line arguments override everything
2. Environment variables — ORG_* prefixed variables
3. Configuration file — TOML file in config directory
4. Default values — Built-in fallbacks

Configuration File Format

[org]
# Root directory containing org-mode files
root_directory = "~/org/"
# Default notes file for new notes
default_notes_file = "notes.org"
# Agenda files to include
agenda_files = ["agenda.org", "projects.org"]
# Extra files for text search beyond regular org files
agenda_text_search_extra_files = ["archive.org"]

[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 files
• ORG_ORG__ORG_DEFAULT_NOTES_FILE — Default notes file name
• ORG_ORG__ORG_AGENDA_FILES — Comma-separated list of agenda files
• ORG_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.