org-records-mcp

org-records-mcp turns your running Emacs into an MCP server over your Org files. An MCP client — Claude Code, Claude Desktop, any other — reads your outline as records, searches it with org-ql, runs your agenda’s questions by name, and writes back through 34 tools and one resource, while the files stay where Org keeps them.

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.

Why it is built this way

• One buffer, not two copies. Calls read and write the buffer visiting the file, not the file behind it. A client sees your unsaved edits, its change lands beside them, and neither of you works on a copy the other has already changed.
• Org does the parsing. Headings, timestamps, tags, properties, links and clocks are read and written through org-element, org-ql, org-clock, org-id and the rest of Org, not through a parser of its own, so what a call sees is what Org sees under your configuration. The handful of patterns org-records-mcp keeps of its own mostly check text a client sends before Org is handed it.
• Records, not text. A heading comes back as typed fields — todo, priority, tags, scheduled, the link that addresses it — and a query or a view returns no bodies unless it asks for them. A client reasons over data and spends its context on the headings that matter.
• org-ql is the query language. org-query takes any org-ql expression, so a client asks the questions your agenda asks, with the same predicates.
• Your agenda, by name. org-view runs views you define from the same org-ql queries your agenda commands use, so the agenda in Emacs and the answer a client gets do not drift apart.
• A foundation, not a workflow. Views, filters, a sort order, computed fields and named field lists are settings a workflow package fills in. agile-gtd is one: an Agile GTD system — epics, projects, next actions, a prioritized backlog — whose public query functions a view can name.

Quickstart

1. Install the package from git — M-x package-vc-install RET https://github.com/stfl/org-records-mcp RET, or in Doom Emacs, in packages.el:

   (package! org-records-mcp
     :recipe (:host github :repo "stfl/org-records-mcp"
              :files (:defaults "org-records-mcp-stdio.sh")))
       

   org-records-mcp is not on MELPA; Installing org-records-mcp has the other routes.

2. Decide which files clients may touch. With an agenda already configured, there is nothing to do: org-records-mcp falls back to org-agenda-files. Otherwise name them, absolute or relative to org-directory:

   (setq org-records-mcp-allowed-files '("inbox.org" "projects/work.org"))
       

3. Install the two stdio shims and start the server, in Emacs:

   M-x mcp-server-lib-install RET
   M-x org-records-mcp-install RET
   M-x mcp-server-lib-start RET
       

4. Register the server with your client:

   claude mcp add -s user -t stdio org-records-mcp -- ~/.emacs.d/org-records-mcp-stdio.sh
       

A client that then calls org-node-read with {"link": "id:550e8400-e29b-41d4-a716-446655440000"} gets the heading, its metadata and its children:

{
  "title": "Project Alpha",
  "todo": "TODO",
  "priority": "A",
  "tags": ["work", "urgent"],
  "scheduled": "<2026-03-26 Thu>",
  "deadline": "<2026-04-01 Mon>",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "level": 1,
  "link": "id:550e8400-e29b-41d4-a716-446655440000",
  "content": "Body text here...",
  "children": [
    {"title": "Subtask", "todo": "NEXT", "level": 2,
     "link": "file:~/org/projects.org::*Subtask"}
  ]
}

Every heading comes back with the link that addresses it, and that link is what the next call sends — the same text org-store-link gives you in Emacs.

What it does not do

• It creates no identifiers. No tool adds an ID or a CUSTOM_ID. A heading without one is addressed by its title, which reaches the first heading of that title and breaks when you rename it. A client that wants a stable address sets the property itself.
• It does not save your dirty buffers. A write into a buffer that already held your unsaved edits stays in that buffer and answers saved: false; the file on disk keeps what it had until you save.
• It reaches the files you allow, and no others. A file outside org-records-mcp-allowed-files is refused unless org-records-mcp-file-scope-override permits it, and then for one call only. Remote (TRAMP) paths are refused before a connection is opened, and so are encrypted .org.gpg files. A clock running in a file outside them is out of reach too, and org-records-mcp discloses nothing about it; you clock out of it in Emacs yourself.
• It refuses a read that would return too much. A read expands as many generations of a heading’s children as you ask for, and stops at org-records-mcp-read-max-nodes nodes, 500 by default. Past that the call is refused, naming the heading it stopped at so you can read that one instead. It is never trimmed to fit, because a shortened answer that does not say so reads like a complete one.
• It blocks Emacs while it searches. A query over a named directory walks the tree and reads every Org file in it in Emacs’s single thread, and Emacs does not respond meanwhile. Point it at narrow directories.
• It ships no views. org-view stays unregistered until you configure views; org-records-mcp has no opinion on what your next actions are.
• It resolves links, it does not follow them. It takes id: and file: links and never runs or opens one, and a search that matches nothing is an error rather than a new heading.

Requirements

Emacs 30.1 or later, with mcp-server-lib and org-ql. CI covers Emacs 30.2 and 31.1 on Linux and macOS. Installing org-records-mcp carries the dependency versions. A heading’s history is read with git, from a repository its file is committed in; nothing else needs it.

Where to go next

Page	Answers
Installing org-records-mcp	Installing the package and the shims, registering an MCP client
Which files a call reaches	The allowed files, naming a file outside them, finding an ID’s file
Addressing headings with links	The link forms a call takes, what is refused, what comes back
Reading Org content	The org://{link} resource, the read tools, the discovery tools
A heading’s history	What changed on one heading since you last looked, from git
Changing Org content	What a write does to your buffers and your files, every write tool
Searching and named views	org-ql queries, and the views a caller runs by name
Clock tracking	Clocking in and out, adding, deleting and repairing clock entries

How it differs from the org-mcp it grew out of is org-records-mcp and org-mcp. Changing the code is CONTRIBUTING: the devshell, the checks, and what a change owes the documentation.

Prior art

org-records-mcp began as a fork of org-mcp by Laurynas Biveinis, and it still runs on his mcp-server-lib.el, which does the MCP protocol work. Serving Org to a model from inside the running Emacs, the allowed files and the first tools are his idea, and over 300 commits of this history are his. The two projects answer differently what a client should get back, which is why this one carries its own name.

License

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