Skip to main content
Glama

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):

  1. Stop org-mcp (e.g. pm2 stop org-mcp) so an in-flight tool call cannot overwrite your restore.

  2. cd <ORG_MCP_DIR>/<user> and inspect the backup to confirm it contains the expected state:

    diff -u inbox.org.bak inbox.org
  3. Copy 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.org

A 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-Assertion header. org-mcp verifies that JWT against your Zero Trust team's public keys and reads the identity from the token's common_name (Service Tokens) or email (interactive logins, including Managed OAuth) claim.

  • A raw X-Org-User header (local dev only): used automatically when CF_ACCESS_TEAM_DOMAIN/CF_ACCESS_AUD aren'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 on 127.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 build

Run 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.js

By 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

PORT

3000

HTTP port to listen on.

HOST

127.0.0.1

Interface to bind. Keep this loopback-only; let cloudflared do the exposing.

ORG_MCP_DIR

~/org-mcp-data

Base directory. Each user gets a subdirectory under it.

ORG_MCP_DEFAULT_FILE

inbox.org

Default capture target filename, per user.

CF_ACCESS_TEAM_DOMAIN

(unset)

Your Zero Trust team domain, e.g. myteam.cloudflareaccess.com. Required together with CF_ACCESS_AUD to enable real auth.

CF_ACCESS_AUD

(unset)

The Access Application's Audience (AUD) tag.

ORG_MCP_IDENTITY_MAP

(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

  1. Install and run cloudflared on 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:404
    cloudflared tunnel route dns <your-tunnel-id> org.example.com
    cloudflared tunnel run <your-tunnel-id>
  2. 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's CF_ACCESS_AUD. Your team domain (Settings → Custom Pages, or the URL of your Zero Trust dashboard) is CF_ACCESS_TEAM_DOMAIN.

  3. 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/).

  4. Add an Access policy on the application allowing those Service Tokens (policy action: Service Auth, selector: the tokens you created).

  5. 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 headers field 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; start cloudflared with sudo 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 save

pm2 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 restart runs without --update-env, so the CF_ACCESS_* vars the process was started with survive the restart. Passing --update-env from 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-run pm2 save.

Local development (no Cloudflare)

npm run dev   # runs src/server.ts directly via tsx, dev-mode auth

Without 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

org_capture

Append a new entry (task, note, or event) to a file, org-capture style. Supports parent_id to nest under an existing entry.

org_agenda

Org-agenda style view: entries scheduled/due in a date range, plus overdue open items.

org_list_todos

List open TODO-like entries by default (unless state is given), sorted by priority/due date; filterable by state, tag, priority, file (with or without .org), and parent_id (descendants).

org_search

Full-text search across headlines, body, and tags (no state filter by default); filterable by state, tag, priority, file (with or without .org), and parent_id (descendants), with optional include_archive (default false).

org_get_entry

Fetch one entry's full details by id.

org_outline

Return a heading tree with descendant TODO counts, filterable by file, rootId, level, and maxDepth (e.g. {file: "inbox.org", level: 1, maxDepth: 1} to list projects).

org_update_state

Change an entry's TODO keyword (e.g. mark DONE); stamps/clears CLOSED.

org_schedule

Set/change/clear SCHEDULED and/or DEADLINE.

org_add_note

Append a timestamped note to an entry's body.

org_refile

Move an entry and its subtree under another entry or into another file.

org_edit_entry

Change an entry's headline, body, or priority.

org_set_tags

Replace an entry's tags.

org_set_properties

Set, update, or remove keys in an entry's :PROPERTIES: drawer (string sets, null removes, omitted keys are unchanged; ID and CREATED are refused).

org_list_tags

List every tag in use, with counts.

org_archive_entry

Move an entry's subtree to <file>_archive.org.

org_read_file

Read the raw text of one tracked org file.

org_list_files

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 tools
org_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_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

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with org-roam knowledge bases, allowing search, retrieval, creation, and linking of notes while respecting org-roam's file structure and conventions.
      15
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local 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.
      39
      10
      AGPL 3.0