org

This MCP server implements the Model Context Protocol (MCP) for org-mode knowledge management. It exposes resources to access and search your org-mode files, retrieve outlines and headings, query agendas, and link content via MCP-compatible tooling. Key resources include org:// for listing files, org-outline:// for file structure, org-heading:// for content by heading, org-id:// for ID-based lookups, and org-agenda:// endpoints for scheduled tasks. Built-in CLI tools (org-cli) and MCP-enabled primitives (org-file-list, org-search, org-agenda) enable programmatic access and automation for organizing and retrieving your org data.

To use it, run the MCP server binary (org-mcp-server). The server will expose endpoints following the MCP protocol. You can query the server with MCP clients or via the included CLI (org-cli) to list org files, search text across files, or fetch agenda items. Typical workflows include indexing org files from configured directories, performing fuzzy searches across content, and retrieving structured outlines or specific headings for downstream tooling or editors that integrate MCP data.

If you’re integrating with an agent or editor, configure the agent to connect to the MCP server’s URI, and leverage resources such as org-search for cross-file queries and org-agenda endpoints for task management in automated workflows.

Prerequisites:

• Rust toolchain (cargo) installed on your system
• Git installed to clone or fetch the repository
• Optional: a configured org directory with your .org files

Install from source:

1. Clone the repository git clone https://github.com/szaffarano/org-mcp-server cd org-mcp-server

2. Build the MCP server and CLI using cargo cargo build --release

3. Run the MCP server cargo run --bin org-mcp-server

4. (Optional) Run the CLI to test access cargo run --bin org-cli -- list

Configuring environment and directories:

• Ensure your org files are accessible and pointed to by the server’s configuration (see README for details on configuration hierarchy and TOML config).
• You can customize logging and CLI output via the configuration file at ~/.config/org-mcp/config.toml or via ORG_* environment variables as documented in the README.

Notes and tips:

• Configuration is TOML-based and supports multiple layers: CLI flags, environment variables, and config files. Review the provided example in the README to tailor org directories, agenda files, and logging.
• Environment variables prefixed with ORG_ control the server behavior (e.g., ORG_SERVER__MAX_CONNECTIONS).
• The server uses the orgize crate for parsing org-mode syntax and rmcp for MCP protocol support, enabling fuzzy search with nucleo-matcher.
• If you containerize the server, you can package the built binary and run it as a separate service. Ensure the MCP port is exposed to clients.
• Common issues often relate to file permissions or missing org files in configured directories; verify that the server user has access to the target directories and that paths are correctly expanded (e.g., ~ and $HOME).
• For debugging, check the log file path configured under [logging] in the TOML config; set ORG_LOGGING__LEVEL to debug or trace for verbose output.