mstodo — Microsoft To Do for Claude

Connect Microsoft To Do to Claude Code and Claude Desktop. Claude can fetch tasks from a specific list (disambiguated by your To Do group folders), plan the work with you, mark tasks done, append timestamped notes, and manage checklists — all in conversation.

Ships as a Claude Code plugin (bundling a self-contained MCP server and a /mstodo planning command), as a one-click Claude Desktop extension (.mcpb), or installable from source. Pick whichever fits — all three are covered below.

Because Microsoft Graph does not expose To Do's group folders, this server keeps its own group→list mapping on disk (~/.mstodo-mcp/groups.json) that mirrors how you organize lists in the To Do app. You teach Claude your groups once, in conversation.

How it works

• Auth: MSAL device-code flow using Microsoft's first-party "Graph Command Line Tools" client ID — no Azure app registration required. You sign in once in a browser; the token is cached to ~/.mstodo-mcp/token-cache.json (chmod 600) and silently refreshed forever after.
• Scope: Tasks.ReadWrite (delegated). Works with personal Microsoft accounts.
• State: ~/.mstodo-mcp/ holds the token cache and the group mapping. Delete token-cache.json to force a fresh sign-in; delete groups.json to reset group assignments.
• Privacy: each person signs into their own Microsoft account and gets their own locally-cached token. Nothing of yours is shared — only the code.

---

Install

Option A — Claude Code plugin (recommended)

Inside Claude Code, add this repo as a plugin marketplace and install it:

/plugin marketplace add furkanzt/claude-mstodo
/plugin install mstodo@mstodo

That's it — one step wires up both the MCP tools and the /mstodo command. The plugin bundles a self-contained server (server/mstodo.mjs, all dependencies inlined), so there's no build step and no npm install.

Requirement: Node.js ≥ 18 on your PATH — the plugin launches the server with node. Check with node --version.

Then, in any conversation, run the command (plugin commands are namespaced by plugin name):

/mstodo:mstodo
/mstodo:mstodo Grad School

…or just talk naturally: "what lists do I have in Microsoft To Do?" The first tool call triggers a browser sign-in (see First-time use).

To update later: /plugin marketplace update mstodo. To remove: /plugin uninstall mstodo@mstodo.

Option B — Claude Desktop extension (one-click)

The whole server is packaged as a Claude Desktop Extension. From the latest release, download mstodo-0.1.0.mcpb, then:

1. Open Claude Desktop → Settings → Extensions.
2. Drag in mstodo-0.1.0.mcpb (or click Install and pick the file) and confirm.
3. Ask Claude "what lists do I have in Microsoft To Do?" — a browser sign-in prompt appears.

No terminal and no Azure setup. (The /mstodo slash command is a Claude Code plugin feature; in Claude Desktop you drive the same tools with the everyday phrases below.)

Option C — from source (manual / development)

git clone https://github.com/furkanzt/claude-mstodo.git
cd claude-mstodo
npm install
npm run build      # compiles TypeScript → dist/

Claude Code — register the built server at user scope:

claude mcp add --scope user mstodo -- node "$(pwd)/dist/index.js"

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (use the absolute path to your node and to dist/index.js), then fully quit and reopen:

"mcpServers": {
  "mstodo": {
    "command": "/opt/homebrew/bin/node",
    "args": ["/absolute/path/to/claude-mstodo/dist/index.js"]
  }
}

To rebuild the shareable .mcpb after changing the code: npm run bundle. To regenerate the plugin's self-contained server bundle: npm run bundle:plugin.

---

First-time use

1. Ask Claude: "What lists do I have in Microsoft To Do?" → it calls todo_get_lists. The first call triggers sign-in: Claude gives you a URL (https://www.microsoft.com/link) and a code. Enter them in a browser, approve, then tell Claude you're done.

2. Teach it your groups (one time). The To Do API can't see your group folders, so tell Claude how your lists are grouped, e.g.:

   "In To Do, my School group has Calculus, Grad School and Ultralearning; my Work group has DenkSoru, KC Üretimi and Project Eddy."

   Claude calls todo_set_groups and stores it. From then on, "fetch the DenkSoru list from Work" resolves correctly, and same-named lists in different groups are disambiguated.

Everyday phrases

• "Fetch the Grad School list from my To Do" → tasks with notes + checklist subtasks.
• "Let's plan these." → normal conversation; Claude reads the tasks.
• "Mark tasks 1, 3 and 4 as done." → todo_complete_tasks (batch).
• "Add a note to the report task explaining what we decided." → todo_add_note (timestamped, appended — never overwrites).
• "Create a task 'Email the client' due next Monday with subtasks draft/review/send."
• "Check off the 'outline' subtask." / "Reopen that task."

Tools

Tool	Purpose
todo_login	Start/check Microsoft sign-in (device code).
todo_get_lists	All lists by group; reconciles mapping; reports renames/deletions.
todo_get_tasks	Tasks from a named list (+group), with notes & checklist. Open-only by default.
todo_create_task	New task with notes, due date, importance, checklist.
todo_complete_tasks	Batch-complete tasks. Detects recurring tasks (advance vs. complete).
todo_update_task	Change title / due date / importance / status (reopen = notStarted).
todo_add_note	Append a timestamped note without erasing existing content.
todo_checklist	Add / check / uncheck subtasks.
todo_set_groups	Assign lists to group folders (mirrors your To Do organization).

Behavior notes (verified against the live API)

• Recurring tasks: completing one advances it to the next occurrence rather than closing it; todo_complete_tasks reports this as recurring_advanced so it isn't mistaken for a failure.
• Due dates are stored at UTC midnight so the calendar date round-trips (no off-by-one).
• Notes are stored as HTML (a To Do requirement) and shown back to Claude as plain text.
• List renames are handled automatically — the mapping is keyed by the stable list id.
• Groups, "My Day", and moving a task between lists are not in the Graph API; only groups are emulated here (via the mapping).

Development

npm run build          # compile to dist/
npm test               # unit tests (resolve + shape)
tsx test/smoke.ts      # end-to-end against a throwaway list (needs a cached token)
npm run inspect        # MCP Inspector against the built server
npm run bundle         # build the Claude Desktop .mcpb (production deps only)
npm run bundle:plugin  # rebuild the plugin's self-contained server/mstodo.mjs

The repo serves three distribution paths from one source tree:

• dist/ — plain tsc output, used by the from-source and .mcpb paths.
• server/mstodo.mjs — a single-file esbuild bundle (deps inlined) committed for the plugin path, so /plugin install runs it with no build step. Regenerate with npm run bundle:plugin whenever src/ changes.
• mstodo-<version>.mcpb — the Claude Desktop extension, shipped as a GitHub Release asset.

Troubleshooting

• Not signed in / expired: ask Claude to sign in again, or run npm run spike login-and-list.
• Plugin server won't start: confirm node --version is ≥ 18 and node is on your PATH (the plugin runs node ${CLAUDE_PLUGIN_ROOT}/server/mstodo.mjs). Run /mcp in Claude Code to see whether the mstodo server registered and which tools it exposes.
• Server won't start in Claude Desktop: check ~/Library/Logs/Claude/mcp-server-mstodo.log. Ensure dist/index.js exists (npm run build) and the command path matches which node.
• Wrong list picked: run "show my To Do lists" to see the mapping; re-run todo_set_groups.
• Use your own Azure app instead of the first-party client ID: register a public client app ("Personal Microsoft accounts only", enable Allow public client flows, add delegated Tasks.ReadWrite), then set MSTODO_CLIENT_ID (and optionally MSTODO_AUTHORITY) in the server's env block. No client secret needed.

License

MIT — see LICENSE.