mlo-mcp

MCP server for the MyLifeOrganized (MLO) Windows desktop app. AI agents (Claude Code, Codex, Cursor, Claude Desktop — anything that speaks MCP over stdio) manage your MLO task tree by driving mlo.exe's undocumented command line locally. No cloud API, no account, your data never leaves the machine.

• 15 tools: list/search/get tasks, contexts, rapid capture, single/atomic-outline add, update/complete/uncomplete/move/delete, write status, QuickSync, cloud status

• Writes never touch your data file: the server runs a local sync endpoint that queues each change as a sync delta and hands it to MLO inside the app's own next sync session, so MLO's own merge logic applies it — the app keeps running, and every accepted write has a receipt you can look up

• Methodology-neutral: the server ships primitives only. Opinionated GTD workflow skills (mindsweep, inbox processing, weekly review, standing conventions) live in a separate gtd-skills repo

Install

Installing is two steps. Step 1 gets you reading — tools that list, search and inspect tasks work as soon as the server is registered. Step 2 enables writing, and it is a one-time setup per profile that cannot be skipped: until it is done, every tool that changes anything refuses.

Requirements

• Windows with MyLifeOrganized desktop installed

• Node 22+ — that's all. The repo ships a committed single-file bundle, so there is no package manager and no dependency install.

Step 1 — Register the server with your MCP client

There is no profile setting. The server operates on whatever profile MLO currently has open (auto-detected by asking the running app itself) and follows you across profile switches. Keep MLO running — it is the only thing that knows which profile is open.

Any MCP client (via npx, straight from GitHub — no npm registry):

{
  "mcpServers": {
    "mlo": {
      "command": "npx",
      "args": ["-y", "github:govza/mlo-mcp"]
    }
  }
}

npx caches the GitHub install; pin a tag (github:govza/mlo-mcp#v0.3.0) for reproducibility, and re-run with a newer tag to update.

Claude Code — either register directly:

claude mcp add mlo -- npx -y github:govza/mlo-mcp

or once for every project, at user scope:

claude mcp add -s user mlo -- npx -y github:govza/mlo-mcp

or install as a plugin (updates via /plugin update):

/plugin marketplace add govza/mlo-mcp
/plugin install mlo@govza

From a clone (no npx):

git clone https://github.com/govza/mlo-mcp
claude mcp add mlo -- node C:\path\to\mlo-mcp\mcp-server\dist-bundle\mlo-mcp.js

Read tools work now. Ask your agent to list your tasks to confirm.

Step 2 — Enable writes (one-time per profile)

Writes are applied by MLO's own sync merge rather than by editing your data file, so the server has to sit in the app's sync path before it can change anything. Until this is finished, add_task, update_task, complete_task and friends all refuse, each naming what is still missing.

1. Back up your .ml profile — a file copy while MLO is closed. Do this before the first sync through the endpoint and before any sync experimentation. If you'd rather rehearse, open a copy of your profile in MLO and run the whole procedure against that.

2. Open MLO with your profile, then start one agent session (any client from Step 1). The session brings up the local sync endpoint in the background — and it has to be up before the next step, because MLO validates your cloud login through the proxy the moment you set it. The endpoint just passes your login through to MLO's cloud; nothing about your account changes.

3. Point MLO's cloud sync through the local endpoint: set the sync profile's proxy to 127.0.0.1:8181, and leave "Use secure connection" unchecked. This matters: with it checked MLO still syncs fine, but the endpoint only sees an opaque TLS tunnel, so setup and every write silently stay dead. MLO's sync log prints "secure connection is OFF for this sync profile" when it is set correctly. Only the MLO↔endpoint hop on your own machine is plaintext: the endpoint re-encrypts before it leaves your machine, so the leg from the endpoint to MLO's cloud is TLS either way.

4. Press Sync in MLO — the ordinary QuickSync button, nothing more. The endpoint recognizes your cloud file, checks that it really is the profile MLO has open, pulls your account's complete history so every pre-existing task gets its stable UID and full record, and only then binds. No MLO restart, no "clear cloud data", no full resync — one regular sync from the UI is the whole handshake.

Ask your agent to check cloud_status to confirm: it should report the profile bound and ready — and if it is not, it now says why the last bind attempt declined.

Writes are live from here. Three things worth knowing:

• A write returns as soon as it is durably queued, not when MLO has applied it. MLO picks it up on its own next sync — usually within about 90 seconds, which the endpoint nudges along. write_status tells you where a given write got to.

• The setup survives client restarts. The endpoint is a background process that outlives your agent sessions; your account credentials stay in its memory and are never written to disk, so a reboot means one more ordinary sync before writes work again. After a reboot the endpoint returns with your first agent session; MLO syncs attempted before that simply fail to connect and retry later, harmlessly.

• cloud_status reports the binding, the partition lifecycle, whether the endpoint is up, and the write queue's health whenever you want to check where things stand.

The full rationale, the merge rules, and what each failure mode looks like are in docs/mcp-cloud.md.

Configuration

None required. The env vars that exist (MLO_EXE_PATH, MLO_CLOUD_PORT, … — all optional) are documented in mcp-server/README.md.

Related MCP server: mcp-task-manager

Documentation

Everything in docs/ was verified empirically against MLO 15.x on Windows — MLO's CLI is largely undocumented, so the quirk catalog there is the map of what actually works.

Disclaimer

Independent project for interoperability and personal use — not affiliated with, authorized by, or endorsed by the makers of MyLifeOrganized. "MyLifeOrganized" and "MLO" are trademarks of their respective owner, used here only to name the app this project interoperates with. It drives a copy of the app you already license and installed, on your own machine and data.

License

MIT