MCP for Microsoft To Do
This MCP server connects AI assistants (Claude, Cursor, etc.) to Microsoft To Do, enabling full task and list management via natural language.
Task & List Management
List, create, retrieve, update, complete, delete, and move tasks across lists
Supports title, body, due date, importance, categories, recurrence patterns, reminders, and status
Search & Discovery
Search tasks across all lists by title keyword
Summarize today's tasks (due today + overdue, per list)
List all tasks across all lists in one request
List overdue tasks or filter tasks by category across all lists
Batch Operations
Batch create, complete, or delete up to 100 tasks in a single API call
Bulk add/remove categories on multiple tasks at once
Sub-tasks (Checklist Items)
List, add, update (rename/check), and delete checklist items within a task
Linked Resources
Attach, list, and delete external URLs or app references on tasks
Custom Metadata (Open Extensions)
Store, retrieve, update, and delete arbitrary JSON metadata (e.g., project IDs) on tasks
Export
Export tasks to iCalendar (.ics) format including recurrence (RRULE) and reminders (VALARM), compatible with Google Calendar, Apple Calendar, Outlook, and Thunderbird
Additional Features
Output in compact text (with localization for English, French, Spanish, German) or verbose Microsoft Graph JSON
Tools annotated as read-only, idempotent, or destructive for safe client integration
mcp-microsoft-todo
π«π· Version franΓ§aise : README.fr.md
MCP server to drive Microsoft To Do from Claude Code, Claude Desktop, or any MCP-compatible client.
Works with any Microsoft account: personal (outlook.com, hotmail.com, live.com), Office 365 personal or business, Microsoft 365. Zero Azure setup required on the user side β just sign in via device code flow.
π Built and maintained by MAG&Cie
This MCP server is open-source and free to use. It's also a showcase of our CrΓ©ation de MCP offering at MAG&Cie β we build custom MCP connectors for businesses that want to plug AI into their internal tools (CRM, ERP, custom APIs, internal databases).
If you'd like the same kind of connector for your tools β drop us a line at www.mag-cie.com/creation-mcp.
Related MCP server: microsoft-todo-mcp-server-self-hosted
π End-user installation
Prerequisites (all clients)
Node.js 20+ (nodejs.org)
A Microsoft account (free or paid)
No Azure account required, no App Registration to create, nothing to compile.
π¦ Claude Code (CLI)
Install (one command):
claude mcp add --transport stdio microsoft-todo -- npx -y @mag-cie/mcp-microsoft-todoIf you have a personal Microsoft account (outlook.com, hotmail.com, live.com, msn.com, Office 365 personal), add MS_TENANT=consumers:
claude mcp add --transport stdio microsoft-todo --env MS_TENANT=consumers -- npx -y @mag-cie/mcp-microsoft-todoVerify it's wired up:
claude mcp listFirst use β recommended: pre-auth in a terminal first to avoid the "stuck on first MCP call" issue (where the device code is printed to MCP stderr but Claude Code doesn't surface it):
# macOS / Linux
MS_TENANT=consumers npx -y @mag-cie/mcp-microsoft-todo@latest --auth# Windows PowerShell
$env:MS_TENANT="consumers"; npx -y @mag-cie/mcp-microsoft-todo@latest --authYou'll see:
To sign in, use a web browser to open the page https://www.microsoft.com/link and enter the code XXXXXXXXXVisit the URL, enter the code, sign in. The token is cached in ~/.mcp-microsoft-todo/token-cache.json and refreshed automatically β you'll never have to do this again. Now go to Claude Code and any prompt that calls a tool will work instantly.
Skip the pre-auth step if you're feeling lucky β the MCP will trigger the device code flow on first call too. The code goes to the Claude Code MCP log file (look in
%USERPROFILE%\.claude\logs\on Windows or~/.claude/logs/elsewhere).
Update to the latest version:
claude mcp remove microsoft-todo
claude mcp add --transport stdio microsoft-todo -- npx -y @mag-cie/mcp-microsoft-todo@latestThe -y flag of npx auto-accepts the download. Without @latest, npx may serve a stale cached version.
Uninstall:
claude mcp remove microsoft-todo
# Purge the token cache:
rm -rf ~/.mcp-microsoft-todoπͺ Claude Desktop (app)
1. Locate the config file:
OS | Path |
Windows |
|
macOS |
|
Linux |
|
On Windows, you can open it directly with:
notepad $env:APPDATA\Claude\claude_desktop_config.jsonIf the file doesn't exist, create it with an empty JSON object {} then edit.
2. Add the config:
{
"mcpServers": {
"microsoft-todo": {
"command": "npx",
"args": ["-y", "@mag-cie/mcp-microsoft-todo"]
}
}
}For a personal Microsoft account, add env:
{
"mcpServers": {
"microsoft-todo": {
"command": "npx",
"args": ["-y", "@mag-cie/mcp-microsoft-todo"],
"env": { "MS_TENANT": "consumers" }
}
}
}To localize the compact-format strings (optional, see Localization):
{
"env": { "MS_TENANT": "consumers", "MCP_LOCALE": "fr" }
}3. Restart Claude Desktop COMPLETELY (not just close the window):
Windows: right-click systray icon β Quit, then relaunch
macOS: β+Q then relaunch
4. Verify it's wired up:
In Claude Desktop, look at the π plug or π§ tools icon at the bottom right of the input area β you should see microsoft-todo listed.
5. First auth β recommended pre-auth in a terminal:
# macOS / Linux
MS_TENANT=consumers npx -y @mag-cie/mcp-microsoft-todo@latest --auth# Windows PowerShell
$env:MS_TENANT="consumers"; npx -y @mag-cie/mcp-microsoft-todo@latest --authYou'll see the device code immediately in the terminal. Visit the URL, enter the code, sign in. Token cached. Now Claude Desktop will reuse this cache β no need to fish in the logs.
Without --auth, the device code goes to the Claude Desktop MCP log file:
Windows:
%APPDATA%\Claude\logs\mcp-server-microsoft-todo.logmacOS:
~/Library/Logs/Claude/mcp-server-microsoft-todo.log
Update: edit the version in args (@mag-cie/mcp-microsoft-todo@latest), restart Claude Desktop. Or let npx do its thing (npx cache ~24h).
π§ Cursor / Continue / other stdio MCP clients
Any MCP client that supports the stdio transport works the same way. Generic format:
command: npx
args: -y @mag-cie/mcp-microsoft-todo
env: MS_TENANT=consumers (if personal account)Adapt to the client's config format (often JSON or TOML similar to Claude Desktop).
π‘ Example prompts
Once installed, just ask Claude in natural language. Sample prompts that exercise the main tools:
Prompt | Tool(s) |
"Show me all my To Do lists" |
|
"What do I have to do today?" |
|
"Show me my overdue tasks" |
|
"List tasks tagged 'work'" |
|
"Find any task containing 'invoice'" |
|
"Add a daily recurring 'Workout' task" |
|
"Mark these 5 tasks as done" |
|
"Move 'Buy bread' from Personal to Shopping" |
|
"Add a 'recipe' subtask to the cake task" |
|
"Tag all my Magaria tasks as 'urgent'" |
|
"Export my work tasks as iCalendar" |
|
"Attach a project_id metadata to this task" |
|
π Auth troubleshooting
Symptom | Solution |
"This page isn't right" page after sign-in | Add |
Browser opens with the wrong Microsoft account | Use an InPrivate/Incognito window for the sign-in |
| Purge the token cache and re-auth: |
| Install Node 20+ from nodejs.org. On Windows, verify it's in PATH (relaunch your terminal after install) |
Token expired, refresh fails | Purge the cache and re-auth |
Device code never appears | Verify the server is spawning β Claude Code: |
| You're using a dev fork β export |
π Available tools (28)
Safety column legend: read = read-only, write = mutates state (non-idempotent create), update = idempotent mutation (safe to retry), delete = destructive (data loss). See Safety annotations below for details.
Lists & tasks
Tool | Safety | Description |
| read | All your To Do lists |
| read | Tasks of a list (OData filter, |
| read | Detail of a task by ID |
| write | Create a task (title, body, importance, due date, categories, recurrence, reminder) |
| update | Update title, status, due date, recurrence, reminder⦠|
| update | Mark as completed |
| delete | Delete permanently |
| delete | Move a task from one list to another (source task is deleted) |
| read | Cross-list search by title |
| read | Summary of tasks due today + overdue |
| read | Every task across every list in one round-trip (uses Graph |
Batch operations (saves API calls)
Tool | Safety | Description |
| write | Create up to 100 tasks in a single Graph |
| update | Mark up to 100 tasks as completed in one call |
| delete | Delete up to 100 tasks in one call |
Sub-tasks (checklist items)
Tool | Safety | Description |
| read | Sub-items of a task |
| write | Add a sub-item |
| update | Rename / check / uncheck |
| delete | Delete a sub-item |
Linked resources (external URLs attached to a task)
Tool | Safety | Description |
| read | List the linked resources of a task |
| write | Attach a URL or external reference |
| delete | Delete a linked resource |
Open extensions (custom JSON metadata)
Tool | Safety | Description |
| read | List the open extensions of a task |
| update | Upsert: create or update an extension (project_id, external_ref, etc.) |
| delete | Delete an extension |
Cross-list helpers
Tool | Safety | Description |
| read | All overdue tasks, aggregated across all lists |
| read | All tasks with a given category, cross-lists |
| update | Add/remove categories on many tasks in 2 batch phases |
Export
Tool | Safety | Description |
| read | iCalendar export (VTODO + RRULE + VALARM) for import into Google Cal / Apple Cal / Outlook / Thunderbird |
Output format
By default, tools return a compact text format (one line per item) to save LLM tokens. Legend:
[!]high importance,[?]low (nothing if normal)[v]completed,[>]in progress,[w]waiting,[d]deferred (nothing if not started)due:,rem:,rec:,cat:,body:fields shown only when populated
To get the full Graph JSON, pass verbose: true to any read tool.
π Safety annotations
Every tool exposed by this server carries the MCP tool annotations defined by the Model Context Protocol spec (2025-06-18):
Annotation | Meaning |
| The tool only fetches data; running it has no side effects on Microsoft Graph |
| The tool deletes data or otherwise causes data loss that cannot be undone |
| Running the tool repeatedly with the same arguments yields the same end state (safe to retry) |
| The tool talks to an external system (Microsoft Graph) β always |
| Human-readable display name for MCP clients |
These hints are advisory β the server itself enforces nothing β but MCP clients (Claude Code, Claude Desktop, Cursor, β¦) can use them to:
Auto-approve
readOnlyHint: truecalls without prompting (faster UX for read-heavy workflows)Show a confirmation dialog before
destructiveHint: truecalls (e.g.delete_task,batch_delete_tasks,move_task)Retry on transient failures only when
idempotentHint: trueDisplay the friendly
titleinstead of the snake_casename
The full mapping is in src/index.ts (ANNOTATIONS constant). Summary by safety class (see also the per-tool Safety column above):
read (15 tools): all
list_*,get_*,search_*,summarize_*,export_*βreadOnlyHint: truewrite (4 tools):
create_*,batch_create_tasksβdestructiveHint: false, idempotentHint: falseupdate (5 tools):
update_*,complete_*,set_extension,bulk_update_categories,batch_complete_tasksβdestructiveHint: false, idempotentHint: truedelete (5 tools):
delete_*,batch_delete_tasks,move_taskβdestructiveHint: true, idempotentHint: true
move_task is classified as delete because it deletes the source task (a new task is created in the target list with a different id).
π Localization
The MCP works in any language out of the box β Claude reads the data the server returns and replies to the user in whatever language they prompted in. Try "List my tasks", "Liste mes tΓ’ches", "Zeig meine Aufgaben", "ζηδ»»ε‘" β all work.
Optionally, you can localize the compact-format short labels returned by the server itself (No tasks., Due today:, Overdue:, Task X deleted., etc.) β this is a marginal improvement (saves a few tokens, slightly cleaner LLM context). Set MCP_LOCALE in your env:
Locale | Code |
English (default) |
|
FranΓ§ais |
|
EspaΓ±ol |
|
Deutsch |
|
Resolution order: MCP_LOCALE β LC_ALL β LANG β fallback en. Only the first 2 chars are inspected (so fr_FR.UTF-8 works). Unsupported locale β falls back to en.
{
"mcpServers": {
"microsoft-todo": {
"command": "npx",
"args": ["-y", "@mag-cie/mcp-microsoft-todo"],
"env": { "MCP_LOCALE": "fr" }
}
}
}π Security & privacy
The Microsoft token is stored only on your machine in
~/.mcp-microsoft-todo/token-cache.jsonNo data transits through MAG&Cie servers
Revoke access at any time at https://account.live.com/consent/Manage
To purge the local token:
rm -rf ~/.mcp-microsoft-todo
Graph permissions requested: Tasks.ReadWrite, Tasks.ReadWrite.Shared, offline_access.
π§βπ» Developer setup (fork / contribution)
If you fork or want to develop locally with your own Azure AD App Registration:
1. Azure AD App Registration (maintainer/fork side only)
https://portal.azure.com β Microsoft Entra ID β App registrations β New registration
Name:
mcp-microsoft-todo(free choice)Supported account types: Accounts in any organizational directory and personal Microsoft accounts
Redirect URI: leave empty
Register
Note the Application (client) ID
Authentication tab β Allow public client flows: Yes
Authentication tab β Add a platform β Mobile and desktop applications β check
https://login.microsoftonline.com/common/oauth2/nativeclientAPI permissions tab β Add a permission β Microsoft Graph β Delegated β add
Tasks.ReadWrite,Tasks.ReadWrite.Shared, andoffline_access. Grant admin consent if on a corporate tenant.
2. Build and local auth
git clone https://github.com/MAG-Cie/mcp-microsoft-todo
cd mcp-microsoft-todo
npm install
npm run build
export MS_CLIENT_ID="<your-client-id>" # PowerShell: $env:MS_CLIENT_ID="..."
export MS_TENANT="common"
npm run authThe token cache will be written to ~/.mcp-microsoft-todo/token-cache.json.
3. Wire up Claude Code (local build)
# Windows PowerShell
$env:MS_CLIENT_ID="<your-client-id>"
claude mcp add --transport stdio microsoft-todo -- node "C:\path\to\mcp-microsoft-todo\dist\index.js"# macOS / Linux
export MS_CLIENT_ID="<your-client-id>"
claude mcp add --transport stdio microsoft-todo -- node /path/to/mcp-microsoft-todo/dist/index.jsβ οΈ Env vars must be visible at spawn time. On Windows with fnm, verify the PowerShell session that launches
claudehasMS_CLIENT_IDexported.
4. Run tests
npm test # one-shot
npm run test:watch # watch modeβ¬οΈ Upgrading from earlier versions
From | To | Action required |
|
| Re-auth required: token cache lacks the new |
|
| No breaking change β new tools added. Token compatible. |
any |
| Stable API marker. Future minor versions guarantee no breaking change to tool names, args, or return formats (compact + verbose). |
πΊ Roadmap
v0.1 β stdio + 6 CRUD tools
v0.2 β distributable npm package, baked-in client ID
v0.3 β recurrence + reminders + checklists + linkedResources + search + move + summarize_today + retry/error robustness + vitest tests + compact format (verbose opt-in)
v0.4 β auto pagination +
$batchoperations +Tasks.ReadWrite.Sharedscope (read shared lists)v0.5 β open extensions + cross-list helpers (overdue, by category, bulk update) + iCalendar export
v1.0 β stable milestone: GitHub Actions CI + extended tests + snapshot tests + README polish
Possible future versions:
v1.1 β file attachments (Graph beta)
v1.2 β auto-pagination follow-on for
summarize_today/search_tasks/list_overdue_tasksv2.0 β remote HTTP/SSE transport for Claude.ai custom connectors (multi-user OAuth)
π License
MIT β Β© MAG&Cie
Available Tools
28 toolsbatch_complete_tasksAIdempotent
Mark several tasks as completed in a single $batch HTTP call (up to 100 items).
Inputs: items (required), verbose.
batch_create_tasksA
Create several tasks in a single HTTP call via Microsoft Graph $batch (up to 100 items, auto-chunked by 20). Returns: status + result OR error per item, in order. More efficient than N create_task calls.
Inputs: items (required), verbose.
batch_delete_tasksBDestructiveIdempotent
Delete several tasks in a single $batch HTTP call (up to 100 items).
Inputs: items (required), verbose.
bulk_update_categoriesAIdempotent
Add/remove categories on several tasks in one operation. 2-phase batch: GET to read existing categories, then PATCH with the updated set. Per-item errors, no global fail.
Inputs: refs (required), add, remove, verbose.
complete_taskCIdempotent
Shortcut to mark a task as completed.
Inputs: list_id (required), task_id (required), verbose.
create_checklist_itemB
Add a sub-item (checklist) to a task.
Inputs: list_id (required), task_id (required), display_name (required), is_checked, +1 more.
create_linked_resourceC
Attach a linked resource (URL or external ref) to a task.
Inputs: list_id (required), task_id (required), web_url, application_name, +3 more.
create_taskC
Create a new task in a To Do list. Supports recurrence and reminder.
Inputs: list_id (required), title (required), body, importance, +8 more.
delete_checklist_itemCDestructiveIdempotent
Delete a sub-item.
Inputs: list_id (required), task_id (required), item_id (required).
delete_extensionADestructiveIdempotent
Delete an open extension from a task.
Inputs: list_id (required), task_id (required), extension_name (required).
delete_linked_resourceCDestructiveIdempotent
Delete a linked resource from a task.
Inputs: list_id (required), task_id (required), resource_id (required).
delete_taskCDestructiveIdempotent
Delete a task permanently.
Inputs: list_id (required), task_id (required).
export_tasks_icsARead-only
Export tasks to iCalendar format (text/calendar VTODO) for import into Google Calendar, Apple Calendar, Outlook, Thunderbird, etc. Recurrence converted to RRULE when possible. Reminder converted to VALARM.
Inputs: list_ids, include_completed, top_per_list.
get_taskCRead-only
Fetch a task's detail by ID.
Inputs: list_id (required), task_id (required), verbose.
list_all_tasksARead-only
Fetch every active task across every list in a single round-trip (uses Graph $batch internally). Use this for the question "what are all my tasks?" instead of NΓlist_tasks calls. Optional filter is an OData filter applied per list (e.g. "importance eq 'high'"). By default status ne 'completed' is appended unless include_completed is true.
Inputs: filter, top_per_list, include_completed, verbose.
list_checklist_itemsCRead-only
List the sub-items (checklist) of a task.
Inputs: list_id (required), task_id (required), verbose, paginate.
list_extensionsBRead-only
List the open extensions (custom JSON metadata) attached to a task.
Inputs: list_id (required), task_id (required), verbose, paginate.
list_linked_resourcesBRead-only
List the linked resources (external URLs, third-party app refs) of a task.
Inputs: list_id (required), task_id (required), verbose, paginate.
list_overdue_tasksARead-only
List ALL overdue tasks (status ne completed and dueDateTime < today) across every list. Aggregated via Promise.all.
Inputs: top_per_list, verbose.
list_task_listsARead-only
List all the user's To Do lists (Tasks, Inbox, custom lists, etc.).
Inputs: verbose, paginate.
list_tasksARead-only
List the tasks of a To Do list. Supports OData filter, $orderby, $top, and pagination.
Inputs: list_id (required), filter, top, orderby, +2 more.
list_tasks_by_categoryARead-only
List ALL tasks containing a given category, across every list. OData filter: categories/any(c: c eq '...').
Inputs: category (required), top_per_list, include_completed, verbose.
move_taskADestructive
Move a task from one list to another. Recreates the task in the target list (title, body, due, recurrence, reminder, categories preserved) then deletes the original. Note: checklistItems and linkedResources are NOT moved (Graph limitation). The task ID changes.
Inputs: source_list_id (required), task_id (required), target_list_id (required), verbose.
search_tasksARead-only
Search a term in the titles of tasks across ALL lists (case-sensitive). By default excludes completed tasks.
Inputs: query (required), top_per_list, include_completed, verbose.
set_extensionBIdempotent
Create or update (upsert) an open extension on a task. Lets you attach arbitrary JSON metadata (project_id, external_ref, custom flags...) that persist in Microsoft Graph.
Inputs: list_id (required), task_id (required), extension_name (required), data (required), +1 more.
summarize_todayARead-only
Summary of tasks due today and overdue, aggregated per list. Useful for the question "what do I have to do today?".
Inputs: time_zone, verbose.
update_checklist_itemAIdempotent
Update a sub-item (rename or check/uncheck).
Inputs: list_id (required), task_id (required), item_id (required), display_name, +2 more.
update_taskCIdempotent
Update an existing task (title, status, recurrence, reminder, etc.).
Inputs: list_id (required), task_id (required), title, status, +10 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 28 tools
Each tool has a clearly distinct purpose, with names that directly indicate their function. Batch operations are clearly separated from single operations, and tools for different resources (tasks, checklist items, linked resources, extensions) are easily distinguishable.
Tool names consistently follow a verb_noun pattern with underscores, using lowercase. Prefixes like batch_, list_, create_, delete_, update_ are used predictably, making the naming scheme intuitive and easy to navigate.
With 28 tools, the server covers a comprehensive set of operations for Microsoft To Do, including batch operations and exports. While a bit on the higher side, the count is justifiable given the domain's complexity and the need to support multiple resource types.
The tool set covers nearly all core workflows: CRUD for tasks, checklist items, linked resources, and extensions; batch operations; search; export; and summary. Minor gaps include the absence of tools to create, update, or delete task lists themselves.
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
MCP server for Nylas β read email, calendars, events and contacts, and send email or create events.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP Server for use with msgraph calls to mail, calendar, and files16MIT
- AlicenseNot gradedqualityCmaintenanceA self-hosted Model Context Protocol server for Microsoft To Do. The key problem this solves: the Microsoft Graph API silently omits user-created lists on personal accounts (GET /me/todo/lists only returns well-known lists like "Flagged Emails"). This server works around it with a local SQLite registry that tracks every list you create, so your lists always show up.3MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor to interact with Microsoft To Do via the Microsoft Graph API.1,108 npmMIT
- AlicenseAqualityBmaintenanceMCP server for Microsoft To Do that enables managing task lists, tasks, and checklist items via the Microsoft Graph API with zero-config authentication.132Apache 2.0