Microsoft To Do MCP

A local-first Model Context Protocol server that lets coding agents work with Microsoft To Do through Microsoft Graph. It uses delegated Microsoft sign-in, encrypted OS-backed token storage, strict tool schemas, structured tool results, modern MCP tool annotations, and STDIO transport. The server supports the current MCP 2026-07-28 protocol and remains compatible with 2025-era MCP clients.

The default core surface keeps the agent's tool list compact. The opt-in full surface adds checklist items, linked resources, file attachments, open extensions, and delta synchronization.

Requirements

• Node.js 20 or newer

• A Microsoft personal, work, or school account with Microsoft To Do

• An Entra app registration you control

• macOS Keychain, Windows DPAPI, or Linux LibSecret for encrypted token storage

Related MCP server: Remote MCP Entra ID Todo

1. Register an Entra application

1. Open the Microsoft Entra admin center and create an app registration.

2. Choose the supported account type that includes the accounts you intend to use. For both work/school and personal Microsoft accounts, choose the multitenant plus personal-account option.

3. Under Authentication, add the Mobile and desktop applications platform and enable the system-browser redirect URI http://localhost.

4. Enable public client flows.

5. Under API permissions, add delegated Microsoft Graph permissions Tasks.ReadWrite and User.Read. Do not create a client secret.

6. Copy the application (client) ID.

Tenant selection defaults to common. Use organizations, consumers, a tenant GUID, or a verified tenant domain when configuring a narrower profile.

2. Install, build, and sign in

npm install
npm run build
node dist/cli.js configure --client-id YOUR_APPLICATION_ID --profile default --tools core
node dist/cli.js auth login --profile default
node dist/cli.js auth status --profile default

The normal login opens the system browser and uses OAuth authorization code flow with PKCE. On a headless machine, add --device-code.

Use named profiles to keep work/school and personal accounts separate:

node dist/cli.js configure --client-id YOUR_APPLICATION_ID --tenant organizations --profile school
node dist/cli.js auth login --profile school

Each running MCP server is pinned to exactly one profile. An agent cannot silently switch Microsoft identities.

3. Add it to Codex

From this repository, use an absolute path to the built CLI:

codex mcp add microsoft-todo -- node /absolute/path/to/microsoft-todo-mcp/dist/cli.js serve --profile default
codex mcp list

Or add this directly to ~/.codex/config.toml:

[mcp_servers.microsoft-todo]
command = "node"
args = ["/absolute/path/to/microsoft-todo-mcp/dist/cli.js", "serve", "--profile", "default"]

Restart the MCP client after changing its configuration. The STDIO process writes protocol messages only to stdout and diagnostic errors to stderr.

Tool surfaces

The core profile exposes:

• todo_lists_list, todo_lists_get, todo_lists_create, todo_lists_update, todo_lists_delete

• todo_tasks_list, todo_tasks_get, todo_tasks_search, todo_tasks_create, todo_tasks_update, todo_tasks_complete, todo_tasks_delete, todo_tasks_move

The full profile additionally exposes CRUD for checklist items, linked resources, attachments, and task open extensions, plus todo_changes_get for Graph delta pages. Select it during configuration or at launch:

node dist/cli.js configure --client-id YOUR_APPLICATION_ID --profile default --tools full
node dist/cli.js serve --profile default --tools full

Task tools accept a list ID or an exact case-insensitive list name. IDs are recommended for automation. Updates and deletes accept optional @odata.etag values to prevent accidental lost updates.

Attachment access

Attachment tools are in the full profile and remain disabled until filesystem roots are explicitly allowlisted:

node dist/cli.js configure --client-id YOUR_APPLICATION_ID --profile default --tools full \
  --attachment-root /Users/me/Documents/AgentAttachments

Files smaller than 3 MiB use direct Graph upload. Larger files use an upload session with sequential chunks; Microsoft To Do's 25 MiB maximum is enforced. Downloads use exclusive creation unless overwrite: true is explicitly passed.

Development

npm run check
npm test
npm run build

The Graph client accepts injected token, fetch, and sleep implementations so pagination, throttling, and errors can be tested without a Microsoft account.

Design boundaries and future remote mode

This release intentionally supports local STDIO and the global Microsoft cloud only. A future remote deployment should preserve the service/tool layer but use stateless Streamable HTTP, MCP authorization discovery, OAuth 2.1 authorization-code flow with PKCE, per-user encrypted server-side token storage, explicit redirect-URI allowlists, CSRF/state protection, and RFC 9728 protected-resource metadata. The local MSAL cache must not be copied to a hosted server.

Notable Microsoft Graph limitations are preserved rather than hidden: task notes are stored as HTML, server-side full-text search is not available for To Do tasks (the search tool scans fetched tasks), and moving a task is implemented as copy-then-delete because Graph has no atomic move endpoint. Task subresources are not copied by that operation.

See SECURITY.md for the trust and credential model.