mstodo-mcp

Use your Microsoft To Do tasks from Claude (or any MCP client), in plain language. This is a personal, self-hosted server that connects Claude.ai to your Microsoft To Do account, so you can ask Claude to find, create, update, complete, search, and organize tasks across all your lists without leaving the chat. It keeps a fast local mirror of your lists and tasks, so searching and querying across every list is quick and doesn't hammer Microsoft on each request.

It runs on either of two hosts with the same tools and sign-in flow:

• Cloudflare Worker — the primary host, documented in DEPLOYMENT.md.
• Node.js or Docker — newer, for self-hosting on a VM or container platform you control, documented in docs/NODE-HOSTING.md.

It's single-user by design: one deployment serves exactly one Microsoft account (everyone else is rejected by an owner-identity gate), so it's meant for running your own private instance — not a shared/multi-tenant service.

Contents

• Requirements
• Tools
• How it works
• Configuration
• Reset
• Identity-change auto-wipe
• Design decisions to revisit
• Author
• Deployment guide →
• Node.js and Docker hosting →
• Changelog →

Requirements

• A Microsoft 365 (M365) or personal Microsoft account that uses Microsoft To Do.
• For the Worker host, a Cloudflare account — the free plan works for small accounts; Workers Paid is recommended once you have thousands of tasks (see the plan note in the deployment guide).
• A Microsoft Entra app registration — free, created once (walkthrough in the deployment guide).
• Node 24 or later, for development and tests (they use Node 24's built-in node:sqlite module); the Worker host also needs Cloudflare's Wrangler CLI, which npm ci installs. The Docker image brings its own Node.
• Claude.ai (or another MCP client) to connect to the deployed server.

➡️ Setup & deployment: see DEPLOYMENT.md for the full step-by-step guide (including the Microsoft Entra app registration), custom-domain setup, and troubleshooting. The Configuration reference is below.

To run without Cloudflare, use the Node.js host: one Node 24 process, or the included Docker image, behind your own HTTPS reverse proxy, with the same tools and sign-in flow and a SQLite file in place of KV and Durable Objects. See docs/NODE-HOSTING.md.

Tools

The server exposes a Microsoft To Do tool surface over MCP. Highlights:

• Lists & tasks (CRUD) — list_lists, get_list, create_list, update_list, delete_list; list_tasks, get_task, create_task, update_task, delete_task, move_task.
• Sub-resources — checklist items and linked resources (create/list/get/update/delete each); attachments (list_attachments, get_attachment, remove_attachment).
• Attachment upload — create_upload_link mints a short-lived, single-use web link the user opens in a browser to attach file(s) to a specific task. The bytes go browser → Worker → Microsoft (≤ 25 MB each, inline or chunked upload-session) and never pass through the model. See Web upload below.
• Attachment download — mint_download_link mints a short-lived (≤ 5 min), single-use URL that serves one attachment's bytes for a server-to-server transfer (e.g. handing the URL to another MCP server's url-ingest tool). The bytes are fetched server-side and never pass through the model. ON by default; set ENABLE_DOWNLOAD_LINKS="false" to disable. See Cross-server download below.
• Cross-list query & search (answered from the local TodoIndex mirror):
  • query_tasks — filter by lists, status, date ranges, importance, has-checklist, has_open_checklist_item (tasks with an unchecked item — the "waiting on something" filter); types/exclude_types (include/exclude by list classification); a completed convenience (mutually exclusive with status); paginated.
  • search_tasks — full-text search over task titles/bodies using FTS5 (SQLite's built-in full-text search engine); same lists/status/types/ exclude_types/completed filters. exclude_types:["excluded"] drops noise (e.g. flagged-email lists) from results without deleting anything. When the checklist cache is on it also matches checklist-item (subtask / step) text by default (include_checklist, tiered after title/body matches).
  • find_task_list, get_pending_across_lists, get_recently_completed.
• Checklist follow-ups (opt-in) — gated behind ENABLE_CHECKLIST_CACHE=true. Mirrors task checklist items into a queryable table so you can use checklist items as a lightweight follow-up system (add a "waiting on Acme reply" item, then find what's still open). search_checklist_items does FTS over checklist text, or — with no query — lists pending items oldest-first (what you've been waiting on longest), grouped by task. Pairs with the query_tasks has_open_checklist_item filter. Off by default (it adds a one-time per-task backfill); the cache then stays fresh on the normal delta cycle. Covers open tasks only — completed tasks are intentionally excluded from cross-task checklist queries (get_task still shows any task's items live), and skipped lists (no_sync/Flagged Emails) aren't cached.
• My Day & manual order (opt-in, Substrate) — gated behind ENABLE_MY_DAY=true (these use the undocumented Substrate endpoint the To Do web app uses, because My Day and the manual drag-to-reorder position are invisible to Graph): list_my_day_tasks, add_to_my_day, remove_from_my_day; list_tasks_by_manual_order (one list in the app's manual order) and reorder_task (move a task to top/bottom, before/after another, or a 1-based slot).
• Config — get_list_config/set_list_config (classification patterns, no_sync, sync_flagged_emails), set_list_alias, get_link_rules/ set_link_rules, get_attachment_config/set_attachment_config, extract_links.
• Ops — whoami, sync_status, resync.

How it works

Claude.ai connects to the Worker over remote-MCP; the Worker brokers requests to the Microsoft Graph API (OAuth authorization-code flow with PKCE + a client secret). A singleton TodoIndex Durable Object (Cloudflare's stateful, strongly-consistent compute primitive) keeps a delta-synced mirror of your lists and tasks in its embedded SQLite database, alongside an FTS5 full-text index (FTS5 is SQLite's built-in full-text search engine). Cross-list query_tasks, search_tasks, and aggregation tools read from this local mirror rather than re-walking Graph on every call; a */15 cron keeps it synced and an owner-identity gate keeps it private.

By default the mirror also subscribes to Graph change notifications (one per list), so an edit in any To Do client lands in the cache within ~2 minutes — near-instant, like the native apps — instead of waiting for the next timer cycle. This is a trigger for delta sync, not a replacement: the timer cycle stays as the backstop (Graph has no missed-notification guarantee for tasks). It rides the existing Tasks.ReadWrite scope (no extra consent), needs a reachable SERVICE_BASE_URL (Graph posts to ${SERVICE_BASE_URL}/webhook), and is toggleable with ENABLE_TASK_SUBSCRIPTIONS ("false" ⇒ timer-only, no public webhook). A notification also refreshes just the changed task's My Day fields via one targeted Substrate read — the webhook path never writes back to Microsoft, so it can't loop.

Small, slowly-changing state — your OAuth tokens, the owner-identity record, and the config blobs below — lives in Cloudflare KV (a key-value store). The large, frequently-queried task corpus lives in the Durable Object's SQLite, not KV.

Security model

The server is strictly single-user by design, and a few invariants are load-bearing — worth stating in one place:

• One owner, fail-closed. Every sign-in is gated at the OAuth callback: the Microsoft /me userPrincipalName must equal the OWNER_EMAIL secret, and a non-matching identity is 403'd before any token is stored. A missing or mistyped OWNER_EMAIL makes the check fail for everyone — it locks the owner out, it never opens access. Setting OWNER_OBJECT_ID also binds sign-in to the account's object ID, which no one can choose. It's required when MS_TENANT_ID is common or organizations, and when OWNER_EMAIL matches the account's mail address instead of its UPN, because an administrator can set mail to any address.
• Per-client consent. Any MCP client can register itself (dynamic client registration), so /authorize shows a consent page naming the client and the address its access will be sent to, and starts the Microsoft sign-in only after you approve. Without it, one click on a crafted /authorize link could hand a grant to someone else's client, because Microsoft sign-in is often silent (the MCP "confused deputy" problem). The page can't be framed or replayed from another browser. Approving with Don't ask again skips it for that client in that browser for 30 days.
• Revocable grants. Every MCP grant carries the auth epoch it was issued under, and every MCP request and token refresh checks it. Calling revoke_all_connections, or signing in as a different Microsoft account, changes the epoch and disconnects every client at once. Grants also expire after 14 days unused, and after 90 days regardless.
• Microsoft access gates cached data too. If Microsoft refuses the stored refresh token (revoked in Entra, expired) or a Conditional Access policy demands a fresh sign-in, every tool — including the ones that read only the local cache — returns reauth_required until you reconnect. A Conditional Access claims challenge is passed to Microsoft on that sign-in.
• Tokens encrypted at rest. The Microsoft tokens in KV are AES-GCM encrypted with a key derived from the MS_CLIENT_SECRET secret, so read access to the KV namespace alone doesn't yield a usable refresh token. Rotating the client secret makes the stored tokens unreadable; reconnect once afterwards.
• Host-pinning before authorization. Every Graph and Substrate URL is pinned to its expected host before the Bearer token is attached, so a malicious @odata.nextLink can't redirect an authenticated request and exfiltrate the token. Tokens travel only in the Authorization header — never in a URL or a log line.
• One token refresher. The singleton TodoIndex Durable Object is the sole caller of the Microsoft token endpoint; concurrent sessions funnel through a single refresh chain, so there are no refresh storms and no token-handling logic duplicated across sessions.
• Regex config is screened. The patterns in config:lists / config:link_rules are writable only through the owner's MCP tools, and set_link_rules / set_list_config also refuse patterns over 256 characters or with a repeated group that contains another repeat ((a+)+), the usual shape of catastrophic backtracking. At run time, link rules read at most 8 KB of a task and the list classifier at most 256 characters of a list name.
• Secret-less web surfaces. /upload and /download authorize with single-use capability tokens — an unguessable random id stored in KV under a TTL, scoped to one task/attachment — so there is no signing key or shared secret to configure or leak.
• Logs carry no secrets. Query strings (which can hold delta tokens) are redacted, Microsoft error bodies are logged as structured fields rather than raw text, failed tool calls log only their reason code, and a rejected sign-in logs only the other account's email domain.

Configuration

Three optional config blobs live in KV under the TODO_CACHE binding. Ready-to-edit examples (with the exact wrangler kv key put commands) are in config-examples/.

config:lists — classification, aliases, sync control

• patterns — ordered regex rules matched against list display names (emoji stripped, case-insensitive by default); first match wins → todo | reference | excluded. Unmatched lists are unclassified. Classification powers list_lists filtering and the types/exclude_types params on query_tasks/search_tasks. excluded keeps a list out of type-filtered tools but does not stop it syncing — use no_sync for that.
• aliases — short handle → Graph list ID, usable anywhere a list is accepted. Cleared automatically on a Microsoft identity switch (IDs are per-account).
• no_sync — lists excluded from delta sync, matched by wellknownListName or Graph list ID. They stay listed and on-demand-readable but aren't indexed. Settable conversationally via set_list_config; the sync loop self-heal-purges a list's rows if you add it later.
• sync_flagged_emails — the flaggedEmails well-known list is skipped by default (it's often huge and not a real task list); set true to index it. This built-in skip is independent of no_sync.

config:link_rules — auto-link tasks

Regex → linked-resource rules applied to task titles/bodies. See config-examples/link-rules.json.

config:attachments — inline upload cap

max_inline_bytes (hard ceiling 3072 KiB, the confirmed Graph limit). For web uploads this is the cutover point: files at or below it are attached inline, larger ones (up to 25 MB) via a chunked Graph upload-session. See config-examples/attachments.json.

Web upload (/upload)

File bytes can't practically travel through an MCP tool call (the model's per-call argument budget is a few KB). Instead, create_upload_link mints a short-lived (default 15 min, max 30), single-use link scoped to one specific task; the user opens it in a browser and the bytes go straight from the browser to the Worker and on to Microsoft Graph — never through the model. Provide a filename for a single-file link, or omit it for a batch link (up to max_files, 1–10, default 5). Identical files already attached to the task are detected by content hash and skipped as duplicates.

The link is a capability token: an unguessable random id (32 bytes from the CSPRNG). The destination scope (list/task ids, filename, file count) is stored server-side in OAUTH_KV under that id with a TTL; the id in the link reveals nothing. Holding the id authorizes one upload to exactly the scoped task — verified by a KV lookup, expired by the TTL, consumed (deleted) on use. There is no signing key or shared secret to configure: the id is the nonce.

To enable it, set SERVICE_BASE_URL (var, in wrangler.jsonc) — the public origin of this Worker (your workers.dev URL or custom domain), used to build the link. With it unset (or left at the placeholder), create_upload_link returns upload_disabled.

Cross-server download (/download)

The inverse of upload: mint_download_link returns a short-lived (≤ 5 min), single-use URL plus the attachment's metadata (filename, content_type, size). The intended consumer is another MCP server's url-ingest tool — it fetches the URL server-side, so the bytes move server → server and never enter the model's context. The capability mechanics mirror upload (an unguessable id in OAUTH_KV under the download: prefix, scoped to one attachment), and the link is burned on the first reachable GET whatever the outcome — so it can't be replayed if it later lands in conversation history. (Single-use against an honest consumer; like /upload it is not transactional — two truly-concurrent GETs could race.) Metadata is read at mint time from the attachments collection, so /download makes a single Graph call for the bytes and trusts no request headers.

The returned size is Graph's reported metadata and can overstate the actual bytes — the authoritative size is the download's Content-Length. The served bytes are byte-exact to the source (verified up to a 4 MiB upload-session attachment), so the transfer is faithful even when size doesn't match. Large attachments work (Graph returns contentBytes on the individual GET regardless of the inline-creation ceiling); the practical limit is Graph's ~25 MB attachment max, since /download buffers the file in Worker memory.

This surface is ON by default; set ENABLE_DOWNLOAD_LINKS="false" (var) to disable both mint_download_link and /download and shrink the attack surface if you don't need it. It also requires SERVICE_BASE_URL (same as upload); unset/placeholder ⇒ download_disabled.

Reset

Three scopes, smallest to largest. Run from the project root; replace --remote with --local if you want to operate on the miniflare local KV store used by wrangler dev.

1. Soft reset between test iterations

Most common: re-trigger the Microsoft OAuth flow without nuking infrastructure. Identity-change auto-wipe (built into /auth/microsoft/callback) will automatically clear the per-identity cache the next time you authorize as a different Microsoft 365 (M365) account, but you can also wipe manually.

# Wipe the stored Microsoft refresh token. Forces the next /authorize to
# re-run the full code-exchange flow.
npx wrangler kv key delete --binding=TODO_CACHE --remote tokens:owner

# Also wipe the stored identity record if you want to "forget" which
# account was last seen (this disables the identity-change wipe trigger
# the next time you sign in — useful when you want to test the wipe).
npx wrangler kv key delete --binding=TODO_CACHE --remote identity:owner

# Wipe all MCP-side OAuth grants (DCR sessions) — forces every
# previously-paired MCP client to re-add this server from scratch:
npx wrangler kv key list --binding=OAUTH_KV --remote \
  | jq -r '.[].name' \
  | xargs -I {} npx wrangler kv key delete --binding=OAUTH_KV --remote {}

To disconnect every MCP client without touching KV, call the revoke_all_connections tool from any connected client. It invalidates every grant at once, including the caller's; each client then reconnects and approves access again.

If you also want Microsoft to re-prompt for consent (rather than silently re-issuing tokens because consent is already on file), either revoke the app from the user's account permissions page on the M365 side, or — once we expose the option — pass &prompt=consent to /authorize.

2. Rotate credentials

Edit .dev.vars with the new values, then push them all to Cloudflare in one go:

bash scripts/push-secrets.sh

The script reads each name from .dev.vars and pipes the value over stdin to wrangler secret put, so values never appear in argv, environment, terminal scrollback, or AI transcripts. Verify with npx wrangler secret list.

Any value in .dev.vars may instead be a 1Password secret reference of the form op://<vault>/<item>/<field> — the script resolves it via the op CLI at push time (requires op signin, or OP_SERVICE_ACCOUNT_TOKEN for headless use) and pipes the resolved value over stdin like any other secret. Literal values still work unchanged, so you can keep some or all secrets out of the file:

MS_CLIENT_SECRET=op://Private/MS To-Do MCP/credential

To push a single secret manually instead:

npx wrangler secret put MS_CLIENT_SECRET     # prompts for value

The old client secret remains valid until you also delete it in the Azure portal — wrangler secret put only updates the Worker side.

After rotating, do a soft reset (above) so the next /authorize uses the new identity.

3. Full clean slate

For pre-launch publishability checks, or to recover from corrupted state:

npx wrangler delete --name=mstodo-mcp                       # nukes Worker + all DO state
npx wrangler kv namespace delete --binding=OAUTH_KV
npx wrangler kv namespace delete --binding=TODO_CACHE
# Then re-create namespaces + update wrangler.jsonc + redeploy (see DEPLOYMENT.md).

This is the "I want this account to look like a fresh fork" path. Note that wrangler delete is destructive and not recoverable.

Identity-change auto-wipe (built in)

When /auth/microsoft/callback completes against a different me.id than the previously stored identity:owner.id, the Worker automatically wipes per-identity state before storing the new tokens. This prevents silently mixing tasks from two M365 accounts.

What the auto-wipe clears, in order (fail-closed — the Durable Object reset runs first, so if it throws nothing else has happened and /authorize aborts before storing the new tokens, never leaving a half-wiped mix):

1. TodoIndex DO reset — drops all indexed tasks, the list roster, and every delta sync_state cursor (the task corpus lives in the DO's SQLite, not KV).
2. tokens:owner then identity:owner in TODO_CACHE (identity marker last, so a failure mid-wipe re-triggers the wipe on the next /authorize rather than silently skipping it).
3. config:lists.aliases — best-effort, since aliases are per-account Graph IDs that would resolve to dead lists after a switch. Classification patterns, no_sync, sync_flagged_emails, config:link_rules, and config:attachments are preserved (account-independent intent).

The auto-wipe also revokes every MCP grant (it bumps the auth epoch — see Security model), so an MCP client paired with the previous account can't read the new account's data. Each client reconnects once.

When the auto-wipe fires, a structured log line is emitted:

{"level":"warn","event":"identity_change_wipe","prev_id":"…","prev_mail":"…","new_id":"…","new_mail":"…","hint":"…"}

You can wrangler tail to watch for it during testing.

Design decisions to revisit

Captured here so future maintainers can reconsider when usage patterns suggest a different tradeoff.

list_tasks pagination — live per-page fetch, no snapshot cache

The Phase 2 list_tasks tool paginates directly against Graph ($top + @odata.nextLink). The next_cursor returned to callers is the opaque Graph nextLink URL; subsequent calls GET that URL through the standard GraphClient token/refresh path. tasks:{listId} is NOT written by this tool — Phase 5 delta sync is the sole writer of that cache key.

This is a documented deviation from the Phase 2 plan's "Cache snapshot to tasks:{listId} with ETag" instruction. Option A (chosen) vs Option B (fetch-all-pages on first call, cache snapshot, slice into pages from cache thereafter):

Axis	A (live, chosen)	B (snapshot)
Graph calls	1 per user page (linear with navigation depth)	1× full-collection fetch on first call; cached reads thereafter
First-page latency	Best — single GET	Worst — must follow all nextLinks before responding
Subsequent-page latency	Same as first	Sub-ms (KV read)
Consistency across pages	Standard REST pagination tearing if tasks change mid-walk	Snapshot-consistent across pages, but the snapshot ages
Cursor shape	Opaque Graph URL, pass-through (prefix-validated against graph.microsoft.com/v1.0/me/todo/lists/)	Our own opaque token (offset or similar)
Code in step 7	~30 lines	~80–100 lines
Phase 5 interaction	Phase 5 delta is sole writer of tasks:{listId}; one owner of cache shape	Phase 5 inherits step-7 cache writes; shape-migration concern if delta needs a different layout
Empirical observability	Each call surfaces real Graph pagination behavior	First call exercises pagination; later calls read cache

Revisit Option B if wrangler tail later shows the LLM repeatedly paginating deep through large lists within short windows — the up-front fetch + cache reads would save Graph quota end-to-end at the cost of first-page latency. As of Phase 2, typical To Do usage is bursty and shallow; live pagination is cheaper overall and lets us defer the cache-shape commitment to Phase 5 where it's load-bearing.

Attachment upload — web /upload, not an MCP tool call

File bytes can't practically travel through an MCP tool call: Claude's per-call output/token budget caps tool arguments at a few KB, so all but trivial uploads fail before Graph is even reached (confirmed while building the sibling obsidian-mcp-cloudflare project). The inline 3072 KiB Graph cap was never the binding constraint — the MCP transport was.

The original create_attachment tool (inline base64 in the tool call) was therefore removed and replaced by the web-upload flow: create_upload_link + the public /upload endpoint (see Web upload). Bytes go browser → Worker → Graph, attached inline for ≤ 3072 KiB and via a chunked upload-session for larger files up to 25 MB. Links are capability tokens — an unguessable random id whose task scope lives in OAUTH_KV under a TTL — task-scoped, single-use, and never generic (every link targets one specific task). No signing key or shared secret is involved. The Worker forwards bytes synchronously during the POST, so no R2 bucket or temporary blob storage is needed. Ported from obsidian-mcp-cloudflare (its src/upload/*), adapted to the To Do attachment APIs and simplified to a secret-less capability token.

Author

Built by David Szpunar. Licensed under the MIT License. Release history in the changelog.