org-mcp
An MCP server for org-capture and org-agenda workflows over plain-text .org files, with multi-user isolation.
Capture new tasks, notes, or events into files with optional body, tags, TODO state, priority, scheduled/deadline dates, and parent nesting.
View agenda-style scheduled/deadline entries for a date range, including overdue open items and optional done entries.
List open TODO-like entries, filterable by exact state, tag, or priority.
Full-text search headlines, body text, and tags, with optional tag filter and archive inclusion.
Fetch full details of a single entry by ID.
Change an entry's TODO state, including DONE/CANCELLED CLOSED timestamp handling.
Set, change, or clear SCHEDULED and DEADLINE timestamps.
Append timestamped notes/log lines to an entry.
Archive an entry and its subtree to a companion
<file>_archive.orgfile.Read raw tracked org files and list tracked files, optionally including archives.
Serve multiple isolated users via per-user directories, using Cloudflare Access auth in production or
X-Org-Userfor local dev; writes use atomic replacement and rolling.bakbackups.
Provides Org-mode style task and note management over plain-text .org files, with tools for capturing entries, viewing agendas, listing TODOs, full-text search, scheduling, updating states, adding notes, and archiving.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@org-mcp Capture a task to review the proposal by Friday"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
org-mcp
An MCP server that gives an LLM org-capture and org-agenda style workflows,
backed by plain-text .org files on local disk. No database — every entry
lives in a human-readable, hand-editable org file you can also open in Emacs.
It speaks MCP over Streamable HTTP, with support for isolating multiple users' data behind Cloudflare Access Service Tokens — built for running on a small always-on box (e.g. a Raspberry Pi) exposed through a Cloudflare Tunnel.
Data model
Entries are ordinary org headlines:
* TODO [#A] File taxes
DEADLINE: <2026-08-19 Wed>
:PROPERTIES:
:ID: 8ece9756-205b-414d-a675-f7def6e231fa
:CREATED: [2026-08-19 Wed 00:21]
:END:Every captured entry gets a stable :ID: (a UUID) so it can be looked up,
rescheduled, or marked done later regardless of edits elsewhere in the file.
Hand-written entries (e.g. typed directly into the file in Emacs) that lack
an :ID: are never modified during reads; instead, read tools return a
temporary tmp:<file>:<line>:<hash> handle. A tmp: handle is valid only
until its file changes: any write to that file, by org-mcp or an external
editor, makes the handle stale, so re-read after each write. On the first
write targeting a valid tmp: handle, org-mcp materializes a permanent
:ID: and applies the edit (reusing that same handle on subsequent calls
within the same server process resolves to the materialized :ID:).
Repeaters and time ranges in timestamps (<2026-08-20 Thu +1w>,
<2026-08-20 Thu 10:00-11:00>) are preserved verbatim across edits — a
state change or a reschedule of one field never rewrites the other.
Atomic writes and backups
Every file write resolves symlinks to the real target, writes to a temporary
file in the real target's directory (.<filename>.<uuid>.tmp), preserves the
existing file's permissions, fsyncs the file, atomically renames it over the
live .org file, and fsyncs the directory — so a crash mid-write cannot
truncate or corrupt it. Note that hard links are split by the rename (use
symlinks if linking a file into another directory).
Before overwriting an existing .org file, the previous version is copied to
<filename>.bak in the same directory as the real file (for example,
inbox.org.bak). This is a rolling one-deep backup of the last version before
the most recent write; .bak and .tmp files are ignored by org_list_files
and all other tools.
To restore a file from its .bak backup (files live in each user's directory,
<ORG_MCP_DIR>/<user>/; for symlinked files, .bak lives next to the real
file, so cd to the real target's directory instead):
Stop
org-mcp(e.g.pm2 stop org-mcp) so an in-flight tool call cannot overwrite your restore.cd <ORG_MCP_DIR>/<user>and inspect the backup to confirm it contains the expected state:diff -u inbox.org.bak inbox.orgCopy the current file aside (so a mistaken restore can be undone), copy the backup over the live file, and restart the server:
cp inbox.org inbox.org.before-restore cp inbox.org.bak inbox.org pm2 start org-mcp
Related MCP server: razberri MCP Server
Multi-user isolation
Every request must resolve to an identity, which maps to a subdirectory:
<ORG_MCP_DIR>/
alice/
inbox.org
projects.org
bob/
inbox.orgA single running server instance serves everyone; each user only ever sees their own subdirectory. There's no cross-user tool for browsing or sharing files — isolation is total.
Identity comes from one of two places:
Cloudflare Access (production): every request that passes an Access policy carries a
Cf-Access-Jwt-Assertionheader. org-mcp verifies that JWT against your Zero Trust team's public keys and reads the identity from the token'scommon_name(Service Tokens) oremail(interactive logins, including Managed OAuth) claim.A raw
X-Org-Userheader (local dev only): used automatically whenCF_ACCESS_TEAM_DOMAIN/CF_ACCESS_AUDaren't set. There's no verification at all in this mode — anyone who can reach the port can claim to be anyone. Only use it on127.0.0.1.
Identity mapping
One person reaches org-mcp under different claims depending on the client.
Claude Code authenticates with a Service Token, yielding its name
(grayson); claude.ai authenticates interactively via Managed OAuth,
yielding an email (j.g.cupit@gmail.com). Left alone those sanitize into two
different directories, so the same human would see two different sets of
tasks depending on which client they opened — which defeats the point of a
shared memory layer.
ORG_MCP_IDENTITY_MAP points at a JSON file mapping each raw claim to a
canonical user id:
{
"grayson": "grayson",
"j.g.cupit@gmail.com": "grayson",
"alice-laptop": "alice",
"alice@example.com": "alice"
}Lookups are case-insensitive and whitespace-tolerant. The mapping is
deliberately explicit rather than inferred — deriving an id by stripping an
email's domain would silently collapse alice@gmail.com and
alice@work.com, two different people, into one directory.
When a map is configured, unmapped identities are rejected with a 403. You're already minting a Service Token per person by hand, so adding a line here at the same time costs nothing, and a loud rejection beats silently creating an empty directory and having the LLM report you have no tasks. The map is read once at startup, so adding a user means restarting the process.
With no map configured, behavior is unchanged: every distinct claim gets its own directory. That keeps local dev and single-identity setups zero-config.
On startup the server logs the claims it loaded and the user ids they resolve to, and logs the resolved id each time a session opens — check those before pointing a second client at a user that already has data.
Setup
npm install
npm run buildRun it:
ORG_MCP_DIR=/home/pi/org-data \
CF_ACCESS_TEAM_DOMAIN=myteam.cloudflareaccess.com \
CF_ACCESS_AUD=<access-app-audience-tag> \
node dist/server.jsBy default it listens on 127.0.0.1:3000 — deliberately loopback-only, so
the only way in is through cloudflared running on the same box. Don't
change HOST to 0.0.0.0 unless you have another reason to trust your LAN.
Environment variables
Variable | Default | Purpose |
|
| HTTP port to listen on. |
|
| Interface to bind. Keep this loopback-only; let |
|
| Base directory. Each user gets a subdirectory under it. |
|
| Default capture target filename, per user. |
| (unset) | Your Zero Trust team domain, e.g. |
| (unset) | The Access Application's Audience (AUD) tag. |
| (unset) | Path to a JSON file mapping Access claims to canonical user ids. See Identity mapping. Unset means every claim gets its own directory. |
Setting only one of CF_ACCESS_TEAM_DOMAIN / CF_ACCESS_AUD is a startup
error — they're required together or not at all.
Exposing it via Cloudflare Tunnel + Access
Install and run
cloudflaredon the same machine as org-mcp, and point an ingress rule at the local port:# ~/.cloudflared/config.yml tunnel: <your-tunnel-id> credentials-file: /home/pi/.cloudflared/<your-tunnel-id>.json ingress: - hostname: org.example.com service: http://localhost:3000 - service: http_status:404cloudflared tunnel route dns <your-tunnel-id> org.example.com cloudflared tunnel run <your-tunnel-id>Create a Zero Trust Access application (dash.cloudflare.com → Zero Trust → Access → Applications) for
org.example.com. Note its Audience (AUD) tag from the app's Overview page — that'sCF_ACCESS_AUD. Your team domain (Settings → Custom Pages, or the URL of your Zero Trust dashboard) isCF_ACCESS_TEAM_DOMAIN.Create one Service Token per user (Zero Trust → Access → Service Auth → Service Tokens). Each token is a Client ID / Client Secret pair with no login flow attached. Give the user's token a name you'll recognize (this name becomes their org-mcp user id, sanitized into a directory name — e.g. a token named "Alice" isolates into
alice/).Add an Access policy on the application allowing those Service Tokens (policy action: Service Auth, selector: the tokens you created).
Give each user their pair. Their MCP client needs to send it as request headers on every call to
https://org.example.com/mcp:CF-Access-Client-Id: <client id>.access CF-Access-Client-Secret: <client secret>How you configure that depends on the client — e.g. a
headersfield in the MCP server config for clients that support remote HTTP servers with custom headers. See "Running under pm2" below for how to keep the server itself alive across reboots; startcloudflaredwithsudo systemctl enable --now cloudflared(or equivalent) so it survives one too.
Restart the server with CF_ACCESS_TEAM_DOMAIN/CF_ACCESS_AUD set once
this is wired up — from then on every request must carry a valid,
Cloudflare-signed identity.
Connecting clients
Which clients can connect depends on how they authenticate, and the two mechanisms need different Access configuration on the same application.
Clients that can send static headers (e.g. Claude Code) use the Service Tokens above directly:
claude mcp add --transport http org-mcp https://org.example.com/mcp \
--header "CF-Access-Client-Id: <client id>.access" \
--header "CF-Access-Client-Secret: <client secret>"Chat clients (claude.ai, Claude Desktop, mobile) can't send custom
headers — their custom-connector UI takes a URL and OAuth only. For those,
turn on Access Managed OAuth
(Zero Trust → Access controls → Applications → your app → Edit → Advanced
settings → Managed OAuth). That makes Access itself the OAuth 2.0
authorization server: the client discovers it at
https://org.example.com/.well-known/oauth-authorization-server, the user
logs in through Access in a browser once, and Cloudflare resolves the
resulting opaque token server-side and forwards the same
Cf-Access-Jwt-Assertion header org-mcp already verifies. No org-mcp code
changes are required — Cloudflare's only requirement for enabling it is
that the origin validate that header, which this server does.
Alongside it you'll want to:
Set Allowed redirect URIs to permit the chat client's callback.
Set Access token lifetime to 5–15 minutes and Grant session duration to 1–2 weeks. Cloudflare recommends this pairing for agent clients: tokens refresh silently in the background, policies are re-evaluated on each refresh, and the user only re-authenticates every couple of weeks.
Add an interactive rule (One-Time PIN or an IdP) to the application's policy. A Service Auth rule can't satisfy a browser login, so it can't carry the OAuth leg — you want both rules on the app, Service Auth for header-based clients and an interactive one for chat clients.
Since the two paths yield different identity claims for the same person, set up Identity mapping before connecting the second client.
Running under pm2
On a box that already runs other services under pm2 (e.g. alongside MagicMirror), start org-mcp the same way rather than introducing a second process manager or an ecosystem file:
export CF_ACCESS_TEAM_DOMAIN=myteam.cloudflareaccess.com
export CF_ACCESS_AUD=<access-app-audience-tag>
pm2 start npm --name org-mcp --cwd ~/org-mcp -- start
pm2 savepm2 save snapshots the resolved environment (including the two exported
vars above) into ~/.pm2/dump.pm2, so pm2 resurrect — run automatically
by the pm2-<user> systemd service set up via pm2 startup — brings it
back with the same config after a reboot. No separate .env file or
ecosystem config needed.
Redeploying
deploy.sh pulls, installs, builds, runs the tests, and restarts the pm2
process — aborting before the restart if any step fails, so a broken build
never replaces a working one. Run it from your own machine in one shot:
ssh pi 'cd ~/org-mcp && ./deploy.sh'Worth aliasing, since that's the whole deploy. It pulls from origin, so
push your commits to GitHub first — otherwise it'll cheerfully redeploy the
code that's already running.
The script sources nvm itself before doing anything. ssh host 'cmd' runs a
non-interactive shell, which returns early from ~/.bashrc before nvm's setup
— so node, npm, and pm2 are all off PATH even though they work fine in
an interactive session. If node is installed some other way on your box, the
script says which command it couldn't find and where to add it.
Two things it deliberately refuses to do:
Deploy over uncommitted changes. If the working tree on the Pi has modifications, it stops rather than pulling over them. Commit, stash, or discard them there first.
Refresh the process environment.
pm2 restartruns without--update-env, so theCF_ACCESS_*vars the process was started with survive the restart. Passing--update-envfrom a plain SSH session would replace them with that shell's empty environment and silently drop Access authentication. If you do need to change those vars, restart it by hand with them exported and re-runpm2 save.
Local development (no Cloudflare)
npm run dev # runs src/server.ts directly via tsx, dev-mode authWithout CF_ACCESS_TEAM_DOMAIN/CF_ACCESS_AUD set, identity comes from an
unauthenticated X-Org-User header (defaulting to "default" if omitted) —
useful for testing multi-user isolation locally, e.g.:
curl -s http://127.0.0.1:3000/mcp \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-H 'x-org-user: alice' \
-H 'mcp-session-id: ...' \
-d '{"jsonrpc":"2.0", ...}'GET /healthz returns {"ok":true} unauthenticated, for uptime checks.
Tools
Tool | Purpose |
| Append a new entry (task, note, or event) to a file, org-capture style. Supports |
| Org-agenda style view: entries scheduled/due in a date range, plus overdue open items. |
| List open TODO-like entries by default (unless |
| Full-text search across headlines, body, and tags (no state filter by default); filterable by |
| Fetch one entry's full details by id. |
| Return a heading tree with descendant TODO counts, filterable by |
| Change an entry's TODO keyword (e.g. mark DONE); stamps/clears |
| Set/change/clear |
| Append a timestamped note to an entry's body. |
| Move an entry and its subtree under another entry or into another file. |
| Change an entry's headline, body, or priority. |
| Replace an entry's tags. |
| Set, update, or remove keys in an entry's |
| List every tag in use, with counts. |
| Move an entry's subtree to |
| Read the raw text of one tracked org file. |
| List tracked org files (for the requesting user). |
Capture fast, organize later
The tools are built around org's two-phase habit rather than forcing structure
at capture time. During a brain dump, org_capture everything flat into the
inbox — no deciding where things belong mid-thought. Later, an "organize my
inbox" pass uses org_refile to cluster entries under project headlines,
org_set_tags to apply a consistent vocabulary, and org_edit_entry to
rework anything captured in a hurry. Refiling carries a whole subtree and
re-levels it, so a project moves with its tasks intact.
org_list_tags exists to stop tag drift. Across many sessions and several
clients, an LLM with no view of the existing vocabulary will invent :work:,
then :job:, then :career: for one concept, and tag-filtered searches
quietly stop finding things. The tool descriptions tell it to check first.
A corollary worth knowing when you use this: not everything should be a TODO. Entries with no todo keyword are plain notes, and standing context ("training for a half marathon in March", "Sarah prefers text over calls") is what makes this a memory layer instead of a task list.
Development
npm run dev # run server.ts directly via tsx
npm test # run the store's functional test suite (uses a temp dir)npm test exercises OrgStore directly (parsing, capture, agenda,
scheduling, archiving, lazy ID assignment) — it doesn't cover the HTTP/auth
layer in server.ts, so changes there are worth a manual smoke test against
a running server.
Available Tools
11 toolsorg_add_noteAdd a timestamped noteA
Append a timestamped note/log line to an existing entry's body.
Inputs: id (required), note (required).
org_agendaAgenda viewA
Get an org-agenda style view: entries scheduled or due within a date range, plus overdue open items when the range covers today. Defaults to today only. Entries with neither SCHEDULED nor DEADLINE never appear here — use org_list_todos for unscheduled open work.
Inputs: end, start, include_done.
org_archive_entryArchive an entryA
Move an entry (and its subtree) out of its source file into a companion <file>_archive.org file. Use this to clean up completed or stale items while keeping a record.
Inputs: id (required).
org_captureCapture a new org entryA
Append a new entry (headline) to a local org file, org-capture style. Use this to jot down tasks, notes, or events. Defaults to file "inbox.org" if none given. Pass parent_id to nest the new entry under an existing entry instead of appending at top level.
Inputs: headline (required), body, file, tags, +5 more.
org_get_entryGet a single entryA
Fetch full details of one entry by its id, including its body text.
Inputs: id (required).
org_list_filesList org filesC
List the org files currently tracked in the org data directory.
Inputs: include_archive.
org_list_todosList TODO entriesA
List open TODO-like entries across all org files (excludes DONE/CANCELLED by default), sorted by priority then due date. Optionally filter by exact state, tag, or priority.
Inputs: tag, state, priority.
org_read_fileRead a raw org fileA
Read the raw text of one tracked org file, exactly as it is on disk. Useful for showing the user their actual file, including any hand-edited content the structured tools don't surface.
Inputs: file (required).
org_scheduleSet SCHEDULED/DEADLINEA
Set, change, or clear the SCHEDULED and/or DEADLINE timestamps on an entry. Omit a field to leave it unchanged; pass null to clear it.
Inputs: id (required), deadline, scheduled.
org_searchSearch entriesA
Full-text search across headlines, body text, and tags in all org files.
Inputs: query (required), tag, include_archive.
org_update_stateChange an entry's TODO stateA
Change the TODO keyword of an entry, e.g. mark it DONE, TODO, NEXT, WAITING, or CANCELLED. Moving into DONE/CANCELLED stamps a CLOSED timestamp; moving out of one clears it.
Inputs: id (required), state (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clearly distinct purposes: capture creates, get_entry reads one entry, search/list_todos/agenda query in different ways, update_state/schedule/archive/add_note mutate different aspects. org_agenda and org_list_todos both surface open work but are differentiated by scheduled/due vs unscheduled, and descriptions explicitly call out the distinction.
All tools use the org_ prefix with verb_noun naming (get_entry, capture, agenda, list_todos, search, update_state, archive_entry, schedule, add_note, read_file, list_files). Minor inconsistency: org_capture and org_agenda are noun/verb-less compared to the verb_noun pattern, but they are conventional org-mode terms and the pattern is otherwise consistent.
11 tools is well-scoped for an org-mode server. Each tool covers a distinct operation needed to interact with org files: querying, capturing, editing state, scheduling, archiving, and file access. No redundant or excessive tools.
The surface covers the core org-mode workflows: capture, list/search/agenda views, state changes, scheduling, notes, archiving, and raw file access. Minor gaps: no tool to edit/rewrite headline text or delete entries outright, and no explicit tool to create a new file, but archiving and raw file read mitigate some of these.
Maintenance
Related MCP Connectors
Brain dump, routines, task planning, focus, and instant thought retrieval
Todos, notes, bookmarks and calendar events — read, add, plan and tidy them.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Notes, kanban tasks, and a capture inbox: read and create Flow data with a personal token.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with org-roam knowledge bases, allowing search, retrieval, creation, and linking of notes while respecting org-roam's file structure and conventions.15MIT
- FlicenseNot gradedqualityDmaintenanceA privacy-first, local-first MCP server that provides 15 ADHD/second-brain tools for capturing, prioritizing, and resurfacing tasks with context from calendar, mail, and messages.1-
- AlicenseNot gradedqualityBmaintenanceEnables agents to capture and manage notes, tasks, events, and links in a private, file-first workspace, with tools for viewing today's agenda and searching Markdown notes.34 npmMIT
- AlicenseAqualityBmaintenanceLocal memory and context for you and your AI agent: notes, tasks and documents as Markdown on your disk. Your agent files tasks with steps and a journal, keeps one living document per subject and picks up where it left off over local stdio, with no account or server. Tisty has no AI inside and never closes or deletes anything.3910AGPL 3.0