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.
A Cloudflare Worker (with Durable Objects) MCP server for a single Microsoft To Do account. Keeps a synced SQLite copy of your lists and tasks for fast, large queries via delta sync. Configurable list-type classification and per-list sync exclusions (flaggedEmails skipped by default).
Estrelas
4
Ferramentas
—
Disponibilidade
—
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.
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:
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).
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_taskshas_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).
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 /meuserPrincipalName 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:
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):
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).
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).
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:
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 ifwrangler 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.
A Cloudflare Worker (with Durable Objects) MCP server for a single Microsoft To Do account. Keeps a synced SQLite copy of your lists and tasks for fast, large queries via delta sync. Configurable list
A Cloudflare Worker (with Durable Objects) MCP server for a single Microsoft To Do account. Keeps a synced SQLite copy of your lists and tasks for fast, large queries via delta sync. Configurable list-type classification and per-list sync exclusions (flaggedEmails skipped by default).
Ferramentas
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Mstodo MCP Cloudflare?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Mstodo MCP Cloudflare precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Mstodo MCP Cloudflare usa?
Mstodo MCP Cloudflare roda localmente via stdio.
Quando Mstodo MCP Cloudflare foi verificado pela última vez?
Última verificação: 2026-10-28. A Cloudflare Worker (with Durable Objects) MCP server for a single Microsoft To Do account. Keeps a synced SQLite copy of your lists and tasks for fast, large queries via delta sync. Configurable list-type classification and per-list sync exclusions (flaggedEmails skipped by default).