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/config.toml (or $XDG_CONFIG_HOME/org-mcp/config.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
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
d

... [View full README on GitHub](https://github.com/szaffarano/org-mcp-server#readme)