org-mcp

Overview

org-mcp is an Emacs package that implements a Model Context Protocol (MCP) server for Org-mode. It enables AI assistants and other MCP clients to interact with your Org files through a structured API.

Installation

From MELPA or MELPA Stable:

M-x package-install RET org-mcp RET

See NEWS for the changelog.

Usage

WARNING: some of the tools in this package give LLMs WRITE access to your Org files, and, once in a thousand invocations, LLMs will try to delete everything, because they are like that. Backups and automatic versioning on every change are strongly advised.

Configuring allowed files

Once you read and internalized the warning above, set the allowed Org file set, using absolute paths:

(setq org-mcp-allowed-files '("/path/to/foo.org" "/path/to/bar.org"))

Registering with an MCP Client

After mcp-server-lib has been properly installed (including M-x mcp-server-lib-install), register org-mcp with your MCP client:

claude mcp add -s user -t stdio org-mcp -- ~/.emacs.d/emacs-mcp-stdio.sh --server-id=org-mcp --init-function=org-mcp-enable --stop-function=org-mcp-disable

Before using the MCP server, you must start it in Emacs with M-x mcp-server-lib-start. Stop it with M-x mcp-server-lib-stop when done.

Available MCP Resources

Note: File paths in URIs use minimal encoding (only # characters are encoded). Avoid using % characters in Org file names.

org://{filename}

• Description: Access the raw content of an allowed Org file
• URI Pattern: org://{filename} where filename is the absolute path to the file
• Configuration: Files must be explicitly allowed via org-mcp-allowed-files using absolute paths
• Returns: Plain text content of the Org file
• Buffer behavior: Reads the file from disk; unsaved changes in an Emacs buffer visiting the file are not reflected.

org-outline://{filename}

• Description: Get the hierarchical structure of an Org file
• URI Pattern: org-outline://{filename} where filename is the absolute path to the file
• Configuration: Files must be explicitly allowed via org-mcp-allowed-files using absolute paths
• Returns: JSON representation of the document structure, up to two levels deep (level-3 and deeper headings are omitted). Each node carries title, level, and children, plus the headline’s todo (state string, or null when none), priority (single-letter string, or null when no [#x] cookie), local tags (array of the headline’s own tags, [] when none — inherited tags are not included), scheduled and deadline (raw timestamp strings, or null), and uri (org-id:// when the headline has an ID property, org-headline:// otherwise).
• Buffer behavior: Reads the file from disk; unsaved changes in an Emacs buffer visiting the file are not reflected.

Example:

# Access via MCP:
URI: org-outline:///home/user/org/projects.org
Returns: JSON structure like:
{
  "headings": [
    {
      "title": "Project Alpha",
      "todo": "TODO",
      "priority": "A",
      "tags": ["work"],
      "scheduled": null,
      "deadline": null,
      "uri": "org-headline:///home/user/org/projects.org#Project%20Alpha",
      "level": 1,
      "children": [
        {
          "title": "Requirements",
          "todo": null,
          "priority": null,
          "tags": [],
          "scheduled": "<2026-06-25 Thu>",
          "deadline": null,
          "uri": "org-headline:///home/user/org/projects.org#Project%20Alpha/Requirements",
          "level": 2,
          "children": []
        }
      ]
    }
  ]
}

org-headline://{filename}#{path}

• Description: Access the content of a specific headline by its path
• URI Pattern: org-headline://{filename}#{path} where:
  • filename is the absolute path (with # encoded as %23)
  • path is URL-encoded headline titles separated by /
  • Headlines containing # must be encoded as %23 in the path
  • Trailing / on filename and empty # fragments are stripped (FILE, FILE/, FILE#, and FILE/# all resolve identically)
• Configuration: Files must be explicitly allowed via org-mcp-allowed-files using absolute paths
• Returns: With a headline path: JSON object with headline_path — the ancestor chain from the outermost ancestor to the read headline itself, in the same node shape as org-grep’s headline_path (see below) — and content, the text of the headline section including all subheadings. With no fragment: the entire file as plain text.
• Buffer behavior: Reads the file from disk; unsaved changes in an Emacs buffer visiting the file are not reflected.

Example:

# Access a headline:
URI: org-headline:///home/user/org/projects.org#Project%20Alpha/Requirements
Returns: JSON with headline_path and content of "Requirements" under "Project Alpha"

# Headline with # character (must be encoded as %23):
URI: org-headline:///home/user/org/projects.org#Issue%20%2342
Returns: JSON with headline_path and content of the "Issue #42" headline

# Access entire file (no fragment):
URI: org-headline:///home/user/org/projects.org
Returns: Full content of the file as plain text

# File with # in the name (must be encoded as %23):
URI: org-headline:///home/user/org/file%231.org#Headline
Returns: JSON for "Headline" from file#1.org

# Both file and headline with # (all encoded):
URI: org-headline:///home/user/org/file%231.org#Task%20%235
Returns: JSON for "Task #5" from file#1.org

Encoding limitations: File paths use minimal encoding (only # → %23) for readability. Files with % characters in their names should be avoided, as they may cause decoding issues. For such files, rename them or use org-id:// URIs instead. Headline paths use full URL encoding.

org-id URI Format

• Description: Access Org node content by its unique ID property
• URI Pattern: org-id://{uuid} where uuid is the value of an ID property
• Configuration: The file containing the ID must be in org-mcp-allowed-files
• Returns: JSON object with headline_path (the ancestor chain in org-grep’s node shape, ending with this headline itself) and content (text of the headline with the specified ID, including all subheadings)
• Buffer behavior: Reads the file from disk; unsaved changes in an Emacs buffer visiting the file are not reflected.

Example:

# Org file with ID property:
* Project Meeting Notes
:PROPERTIES:
:ID: 550e8400-e29b-41d4-a716-446655440000
:END:
Meeting content here...

Access via MCP:

• URI: org-id://550e8400-e29b-41d4-a716-446655440000
• Returns: Content of “Project Meeting Notes” section

Available MCP Tools

Note: All write tools will create Org IDs for any touched nodes that did not have them originally. The IDs will be returned in the tool response.

Note: Full semantics for each tool live in its MCP description string, surfaced by clients via tools/list; the summaries below mirror those descriptions.

org-get-todo-config

• Description: Get TODO keyword configuration for understanding task states
• Parameters: None
• Returns: JSON object with sequences and semantics

Example response:

{
  "sequences": [
    {
      "type": "sequence",
      "keywords": ["TODO", "NEXT", "|", "DONE", "CANCELLED"]
    }
  ],
  "semantics": [
    {"state": "TODO", "isFinal": false, "sequenceType": "sequence"},
    {"state": "NEXT", "isFinal": false, "sequenceType": "sequence"},
    {"state": "DONE", "isFinal": true, "sequenceType": "sequence"},
    {"state": "CANCELLED", "isFinal": true, "sequenceType": "sequence"}
  ]
}

org-get-tag-config

• Description: Get tag configuration as literal Elisp variable values
• Parameters: None
• Returns: JSON object with literal Elisp strings for all tag-related variables

Example return value:

{
  "org-use-tag-inheritance": "t",
  "org-tags-exclude-from-inheritance": "(\"urgent\")",
  "org-tag-alist": "((\"work\" . 119) (\"urgent\" . 117) (:startgroup) (\"@office\" . 111) (\"@home\" . 104) (\"@errand\" . 101) (:endgroup) (:startgrouptag) (\"project\") (:grouptags) (\"proj_a\") (\"proj_b\") (:endgrouptag))",
  "org-tag-persistent-alist": "nil"
}

org-get-allowed-files

• Description: Get the list of Org files accessible through the org-mcp server
• Parameters: None
• Returns: JSON object with files array containing absolute paths of allowed Org files

Use cases:

• Discovery: “What Org files can I access through MCP?”
• URI Construction: “I need to build an org-headline:// URI - what’s the exact path?”
• Access Troubleshooting: “Why is my file access failing?”
• Configuration Verification: “Did my org-mcp-allowed-files setting work correctly?”

Example response:

{
  "files": [
    "/home/user/org/tasks.org",
    "/home/user/org/projects.org",
    "/home/user/notes/daily.org"
  ]
}

Empty configuration returns:

{
  "files": []
}

org-get-agenda-config

• Description: List the custom agenda commands defined in org-agenda-custom-commands. A runnable key can be passed as org-get-agenda’s view.
• Parameters: None
• Returns: JSON object with a commands array, one entry per org-agenda-custom-commands definition:
  • key: the command’s dispatch key string
  • description: the command’s description
  • type: the command’s kind, one of prefix (a bare key group), agenda, agenda*, todo, todo-tree, alltodo, tags, tags-todo, tags-tree, search, occur-tree, stuck, composite (a multi-block command), or function (a user function)
  • raw: present only for function entries — the entry’s literal Elisp, as a fallback for a client that wants to inspect it
• Note: type is reported as a fact and does not promise runnability.

Example response:

{
  "commands": [
    {"key": "p", "description": "Projects", "type": "tags-todo"},
    {"key": "n", "description": "Next actions", "type": "todo"},
    {"key": "h", "description": "Home", "type": "prefix"},
    {"key": "r", "description": "Weekly review", "type": "composite"},
    {"key": "x", "description": "Custom", "type": "function",
     "raw": "(\"x\" \"Custom\" my-agenda-fn)"}
  ]
}

org-get-agenda

• Description: Run an Org agenda view and return both its plain text and its entries as structured data. The view is either a builtin span (day, week, month, aligned with org-agenda-day-view, org-agenda-week-view, and org-agenda-month-view) or a dispatch key from org-agenda-custom-commands.
• Parameters:
  • view (string, required): day, week, or month (case-insensitive, reserved for the builtin spans), or any dispatch key defined in org-agenda-custom-commands (discover keys with org-get-agenda-config)
  • date (string, optional): Any string org-read-date accepts; omit to use today (an empty or whitespace-only string is rejected). Fixes which day / week / calendar month the agenda covers. How unrecognized input is treated follows your installed Org version. Applies only to the day/week/month spans; every custom-command view ignores it (a custom agenda block always anchors on today).
• Scope: The agenda is built only from org-mcp-allowed-files entries that exist on disk. It does not pull in other org-agenda-files the user may have configured in Emacs. Caveat: a custom command whose own settings set org-agenda-files or a restriction can override this and escape the allow-list.
• Returns: JSON with:
  • view: the span name or the custom dispatch key you passed
  • date: your string, or the literal today if omitted
  • start_day: for a span, the first day the agenda covers, as YYYY-MM-DD (resolved; a month snapped to the first of the calendar month, a week aligned per your org-agenda-start-on-weekday — the reference day itself when that is nil); null for a non-dated custom view
  • agenda: the full agenda buffer text, unchanged — including any lines (diary, clock, informational) that have no source heading
  • blocks: array of agenda blocks (one for a span view — its items may be empty; several for a composite custom command). Each block has header (the block’s header line, or null) and items (array of entry nodes — title, todo, priority, tags, scheduled, deadline, uri, the same node shape org-grep emits). A heading appears at most once per block — a multi-day span entry the text shows on several days is a single item. Agenda lines with no source heading appear only in agenda text, not in items.
• Prompting commands: A custom command that prompts for input (a tags or search command with no baked-in match, or a bare prefix key) cannot run non-interactively and is rejected with an error.

org-grep

• Description: Search for a literal substring across one or all allowed Org files
• Parameters:
  • pattern (string, required): Literal substring to search for. Must be non-empty and single-line (no newlines). Not a regex.
  • file (string, optional): Absolute path to an allowed Org file. When omitted, all org-mcp-allowed-files are searched.
  • case_sensitive (boolean, optional, default false): When true, the match is case-sensitive.
• Returns: JSON object with a groups array. Each group represents a contiguous run of matching lines within one section:
  • file: absolute path of the source file
  • headline_path: array of node objects tracing the path to the containing section, from the outermost ancestor to the section’s own headline (empty array for content before the first heading). Each object has title, todo (state string or null), priority (single-letter string or null), local tags (array of the headline’s own tags, [] when none), scheduled and deadline (raw timestamp strings or null), and uri (org-id:// or org-headline://). The last entry’s uri equals the group uri below.
  • uri: resource URI — org-id:// when the section has an ID, org-headline:// otherwise. Pass directly to resources/read. To use the read tools instead, extract the uuid (for org-read-by-id) or the file and fragment path (for org-read-headline) from the URI.
  • matches: array of {line, text} objects — line is the 1-based line number, text is the full line content
• Group rules: Groups appear in document order, per file in org-mcp-allowed-files order. A new group starts whenever the containing section changes. One match per source line.
• Configuration: Searched files must be in org-mcp-allowed-files. Returns {"groups": []} when no files are configured and no file is given.
• Buffer behavior: Reads files from disk; unsaved changes in Emacs buffers are not reflected.

org-find-tagged-ancestor

• Description: Find the nearest enclosing headline that carries a given tag as its own (local) tag
• Parameters:
  • uri (string, required): URI of the headline to start from (supports org-headline:// or org-id://); must identify a headline, not a whole file
  • tag (string, required): Single tag name to look for (non-empty)
  • include_self (boolean, optional, default false): When true, the headline at uri is checked before its ancestors
• Returns: JSON object with a single found key: the node object of the nearest self-or-ancestor headline whose own tag list contains tag — same node shape as org-grep’s headline_path entries (title, todo, priority, tags, scheduled, deadline, uri; org-id:// when the headline has an ID, org-headline:// otherwise) — or null when no enclosing headline declares the tag
• Semantics: Each level is tested against its local tags only. Tags a headline merely inherits from an ancestor or from #+FILETAGS never match (a tag declared only in #+FILETAGS has no declaring headline, so the result is null), and org-tags-exclude-from-inheritance is deliberately ignored. Under Org’s default tag inheritance, a non-null result with include_self set to true means the headline carries the tag.
• Configuration: File must be in org-mcp-allowed-files
• Buffer behavior: Reads the file from disk; unsaved changes in an Emacs buffer visiting the file are not reflected.

org-update-todo-state

• Description: Update the TODO state of a specific headline
• Parameters:
  • uri (string, required): URI of the headline (supports org-headline:// or org-id://)
  • current_state (string, required): Current TODO state (empty string “” for no state) - must match actual state
  • new_state (string, required): New TODO state (must be valid in org-todo-keywords, or empty string “” to clear to no keyword)
• Returns: Success status with previous and new states, and ID-based URI of the updated headline. new_state is the actual resulting state, which may differ from the request (e.g. a repeating entry marked done is reset to its not-done keyword)
• Buffer behavior: Modifies the file on disk; fails if an Emacs buffer visiting the file has unsaved changes; ask the user to save the buffer and retry.
• Blocked transitions: If a member of org-blocker-hook (e.g. a TODO-dependency or unchecked-checkbox blocker) vetoes the change, the tool returns an error and leaves the file unchanged, rather than reporting success.

Example:

# Request:
{
  "uri": "org-headline:///home/user/org/projects.org/Project%20Alpha",
  "current_state": "TODO",
  "new_state": "IN-PROGRESS"
}

# Success response:
{
  "success": true,
  "previous_state": "TODO",
  "new_state": "IN-PROGRESS",
  "uri": "org-id://554A22F6-E29F-4759-8AD2-E7CA225C6397"
}

# State mismatch error:
{
  "error": "State mismatch: expected TODO, found IN-PROGRESS"
}

org-edit-headline

• Description: Edit an existing headline’s title and/or local tags, preserving its TODO state, planning, properties, and body
• Parameters:
  • uri (string, required): URI of the headline (supports org-headline:// or org-id://)
  • current_title (string, required): Current headline title (without TODO state or tags) - must match actual title
  • new_title (string, optional): New headline title (without TODO state or tags)
  • add_tags (string or array, optional): Local tags to add (e.g., “@office” or [“work”, “urgent”])
  • remove_tags (string or array, optional): Local tags to remove
  • At least one of new_title, add_tags, remove_tags must be supplied; a tag cannot appear in both add_tags and remove_tags
• Returns: The updated node: success, title, todo, priority, tags (resulting local tags), scheduled, deadline, uri
• Buffer behavior: Modifies the file on disk; fails if an Emacs buffer visiting the file has unsaved changes; ask the user to save the buffer and retry.
• Tag semantics:
  • Tag edits are a delta over the headline’s own (local) tags and are idempotent: adding a present tag or removing an absent one is a no-op.
  • add_tags are validated against the globally configured org-tag-alist / org-tag-persistent-alist (rejected if unknown); a file’s own #+TAGS: additions are not honored, so a file-local tag not in the global alist is rejected. remove_tags accept any syntactically valid tag so a tag no longer in the alist can still be dropped.
  • Local tags only: an inherited tag (e.g. one applied by a container heading or #+FILETAGS) cannot be shed here; move the headline out of the tagged subtree with org-refile-headline instead.
  • Mutual-exclusion groups are not auto-enforced across the resulting set (adding a group member to a headline that already carries another keeps both); swap within a group by passing the old tag in remove_tags and the new one in add_tags in the same call. A single add_tags list may not itself contain two members of the same group.
  • Adding or removing the crypt tag changes only the tag; it does not trigger org-crypt encryption or decryption.

Example:

# Request (swap context tag and retitle in one call):
{
  "uri": "org-headline:///home/user/org/projects.org/Buy%20milk",
  "current_title": "Buy milk",
  "new_title": "Buy oat milk",
  "add_tags": ["@office"],
  "remove_tags": ["@home"]
}

# Success response:
{
  "success": true,
  "title": "Buy oat milk",
  "todo": "TODO",
  "priority": null,
  "tags": ["@office"],
  "scheduled": null,
  "deadline": null,
  "uri": "org-id://550e8400-e29b-41d4-a716-446655440002"
}

# Title mismatch error:
{
  "error": "Title mismatch: expected 'Original Task', found 'Different Task'"
}

org-add-todo

• Description: Add a new TODO item to an Org file
• Parameters:
  • title (string, required): The headline text
  • todo_state (string, required): TODO state from org-todo-keywords, or empty string “” for a headline with no keyword
  • tags (string or array, required): Tags to add (e.g., “urgent” or [“work”, “urgent”])
  • body (string, optional): Body text content to add under the heading
  • parent_uri (string, required): URI of parent item. Use org-headline://filename.org/ for top-level items in a file (also accepted: org-headline://filename.org, org-headline://filename.org#, org-headline://filename.org/# — not recommended).
  • after_uri (string, optional): URI of sibling to insert after; omit to append as last child. Cannot be combined with a top-level parent_uri or with position, and cannot reference parent_uri itself. See the MCP tool description for accepted formats.
  • position (string, optional): Where to place the new item: "start" or "end" (default "end"). At top level, "start" inserts after leading #-prefixed lines and drawers, before the first existing heading. See the MCP tool description for full placement rules and the mutex with after_uri.
• Returns: Object with success status, new item URI, file name, and title
• Buffer behavior: Modifies the file on disk; fails if an Emacs buffer visiting the file has unsaved changes; ask the user to save the buffer and retry.

Example:

# Request:
{
  "title": "Implement new feature",
  "todo_state": "TODO",
  "tags": ["work", "urgent"],
  "body": "This feature needs to be completed by end of week.",
  "parent_uri": "org-headline:///home/user/org/projects.org/"
}

# Success response:
{
  "success": true,
  "uri": "org-id://550e8400-e29b-41d4-a716-446655440001",
  "file": "projects.org",
  "title": "Implement new feature"
}

org-edit-body

• Description: Edit body content of an Org node using partial string replacement
• Parameters:
  • resource_uri (string, required): URI of the node to edit (supports org-headline:// or org-id://)
  • old_body (string, required): Substring to search for within the node’s body (must be unique unless replace_all is true). Use empty string “” to add content to an empty node
  • new_body (string, required): Replacement text
  • replace_all (boolean, optional): Replace all occurrences (default: false)
• Returns: Success status with ID-based URI of the updated node
• Special behavior: When old_body is an empty string (“”), the tool will only work if the node has no body content, allowing you to add initial content to empty nodes
• Buffer behavior: Modifies the file on disk; fails if an Emacs buffer visiting the file has unsaved changes; ask the user to save the buffer and retry.

Example:

# Request:
{
  "resource_uri": "org-id://abc-123",
  "old_body": "This is a placeholder.",
  "new_body": "Implementation started - using Strategy pattern."
}

# Success response:
{
  "success": true,
  "uri": "org-id://abc-123"
}

# Adding content to empty node:
{
  "resource_uri": "org-id://new-task",
  "old_body": "",
  "new_body": "Initial task description."
}

org-set-planning

• Description: Set, change, or clear a headline’s SCHEDULED and/or DEADLINE planning timestamps
• Parameters:
  • uri (string, required): URI of the headline (supports org-headline:// or org-id://)
  • scheduled (string, optional): Timestamp content to schedule, as written inside <...>: a date, optional time-of-day, and optional repeater/warning cookies. Examples: 2026-06-20, 2026-06-20 14:00, +1w (one week from today), 2026-06-20 +1w -3d. The first whitespace token is the date (so a lone +1w is a relative date, not a repeater); trailing +N, ++N, .+N (with unit h/d/w/m/y, optionally with a /M habit interval) set a repeater and -N sets a warning period
  • deadline (string, optional): Same grammar as scheduled, for the DEADLINE timestamp
  • clear_scheduled (boolean, optional): Remove the SCHEDULED entry (default: false)
  • clear_deadline (boolean, optional): Remove the DEADLINE entry (default: false)
• Returns: Success status, the resulting scheduled and deadline timestamp strings (null when absent), and the ID-based URI of the headline
• Constraints: At least one of scheduled, deadline, clear_scheduled, clear_deadline must be provided. A field and its clear_* cannot be combined, and an empty scheduled=/=deadline string is rejected (use clear_* to remove)
• Repeater/warning handling: Org produces the relative-date resolution, weekday names, and planning-line placement. When re-scheduling, omitting cookies preserves an existing repeater/warning; including any cookie replaces the field’s existing cookies
• Buffer behavior: Modifies the file on disk; fails if an Emacs buffer visiting the file has unsaved changes; ask the user to save the buffer and retry.

Example:

# Request (schedule with a weekly repeater, set a deadline):
{
  "uri": "org-id://abc-123",
  "scheduled": "2026-06-20 +1w",
  "deadline": "2026-06-25"
}

# Success response:
{
  "success": true,
  "scheduled": "<2026-06-20 Sat +1w>",
  "deadline": "<2026-06-25 Thu>",
  "uri": "org-id://abc-123"
}

# Clear the scheduled date:
{
  "uri": "org-id://abc-123",
  "clear_scheduled": true
}

# Success response (SCHEDULED removed; DEADLINE retained):
{
  "success": true,
  "scheduled": null,
  "deadline": "<2026-06-25 Thu>",
  "uri": "org-id://abc-123"
}

org-archive-subtree

• Description: Archive an Org headline subtree to its configured archive location
• Parameters:
  • uri (string, required): URI of the headline to archive (supports org-headline:// or org-id://)
• Returns: Success status, the absolute archive file path, and the archived headline’s org-id:// URI. The archive file path equals the source file’s own path when the archive location is in-file (empty file part before ::)
• URI resolvability: The returned org-id:// URI identifies the archived headline but is resolvable via resources/read only if the archive file is itself a member of org-mcp-allowed-files; otherwise it is informational only
• Archive location: Honors the headline’s ARCHIVE property, then the file’s #+ARCHIVE: setting, then the global org-archive-location, in that order. The subtree is always moved to that archive file regardless of org-archive-default-command.
• Buffer behavior: Modifies the source and archive files on disk; fails if an Emacs buffer visiting either has unsaved changes; ask the user to save the buffer and retry.

Example:

# Request (headline lacks an ID; the tool mints one):
{
  "uri": "org-headline:///home/user/org/projects.org#Project%20Alpha/Old%20Task"
}

# Success response (returns the freshly minted org-id:// URI):
{
  "success": true,
  "archive_file": "/home/user/org/projects.org_archive",
  "uri": "org-id://550e8400-e29b-41d4-a716-446655440003"
}

org-refile-headline

• Description: Move an existing headline and its entire subtree to a new parent or file, preserving its TODO state, tags, properties, ID, body, and child structure
• Parameters:
  • uri (string, required): URI of the headline to move (supports org-headline:// or org-id://); must identify a headline, not a whole file
  • current_title (string, required): Current headline title (without TODO state or tags) - must match actual title
  • target_parent_uri (string, required): URI of the new parent. Use org-headline://filename.org/ for a top-level destination, or a headline / org-id:// URI to move under that node. Same shape as org-add-todo’s parent_uri.
  • after_uri (string, optional): URI of sibling to place after; omit to append as last child. Cannot be combined with a top-level target_parent_uri or with position, and cannot reference uri itself. See the MCP tool description for accepted formats.
  • position (string, optional): Where to place among the target’s children: "start" or "end" (default "end"). Mutually exclusive with after_uri.
• Returns: Object with success status, the moved node’s org-id:// URI, title, and source and target file names
• Source and target files: Both must be members of org-mcp-allowed-files. The existing ID is preserved, including across files.
• Rejected moves: Moving a node into itself or its own subtree is rejected.
• No-op: When the node already sits in the requested place (same parent and slot) and already has an ID, the file is left untouched.
• Buffer behavior: Modifies the source file, and the target file when different, on disk; fails if an Emacs buffer visiting either has unsaved changes; ask the user to save the buffer and retry.

Example:

# Request (move an inbox item under a project, given by the project's ID):
{
  "uri": "org-headline:///home/user/org/inbox.org#Buy%20milk",
  "current_title": "Buy milk",
  "target_parent_uri": "org-id://550e8400-e29b-41d4-a716-446655440000"
}

# Success response (the moved headline lacked an ID; the tool mints one):
{
  "success": true,
  "uri": "org-id://550e8400-e29b-41d4-a716-446655440099",
  "title": "Buy milk",
  "source_file": "inbox.org",
  "target_file": "projects.org"
}

Workaround Tools Duplicating Resource Templates

Note: The following tools are temporary workarounds that duplicate the resource template functionality as tools. They exist because Claude Code currently doesn’t discover resource templates.

org-read-file

• Description: Read complete raw content of an Org file
• Parameters:
  • file (string, required): Absolute path to an Org file
• Returns: Plain text content of the entire Org file
• Configuration: File must be in org-mcp-allowed-files
• Buffer behavior: Reads the file from disk; unsaved changes in an Emacs buffer visiting the file are not reflected.

org-read-outline

• Description: Get hierarchical structure of an Org file as JSON outline
• Parameters:
  • file (string, required): Absolute path to an Org file
• Returns: JSON object with hierarchical outline structure. See the org-outline:// resource above for the per-node fields (title, todo, priority, tags, scheduled, deadline, uri, level, children).
• Configuration: File must be in org-mcp-allowed-files
• Buffer behavior: Reads the file from disk; unsaved changes in an Emacs buffer visiting the file are not reflected.

org-read-headline

• Description: Read specific Org headline by hierarchical path
• Parameters:
  • file (string, required): Absolute path to an Org file
  • headline_path (string, required): Non-empty slash-separated path to headline. Only slashes within headline titles must be URL-encoded as %2F to distinguish them from path separators. Other characters (spaces, #, etc.) do not need encoding. To read entire files, use org-read-file instead
• Returns: JSON object with headline_path — array of node objects from the outermost ancestor to the read headline itself, in the same node shape as org-grep’s headline_path (title, todo, priority, tags, scheduled, deadline, uri) — and content, the text of the headline and its subtree
• Configuration: File must be in org-mcp-allowed-files
• Buffer behavior: Reads the file from disk; unsaved changes in an Emacs buffer visiting the file are not reflected.

org-read-by-id

• Description: Read Org headline by its unique ID property
• Parameters:
  • uuid (string, required): UUID from headline’s ID property
• Returns: JSON object with headline_path and content, same shape as org-read-headline
• Configuration: File containing the ID must be in org-mcp-allowed-files
• Note: More stable than path-based access since IDs don’t change when headlines are renamed or moved
• Buffer behavior: Reads the file from disk; unsaved changes in an Emacs buffer visiting the file are not reflected.

License

This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details.