{
  "markdown": "# mcp-microsoft-todo\n\n> 🇫🇷 Version française : [README.fr.md](README.fr.md)\n\nMCP server to drive **Microsoft To Do** from Claude Code, Claude Desktop, or any MCP-compatible client.\n\nWorks 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.\n\n[![npm](https://img.shields.io/npm/v/@mag-cie/mcp-microsoft-todo.svg)](https://www.npmjs.com/package/@mag-cie/mcp-microsoft-todo)\n[![license](https://img.shields.io/npm/l/@mag-cie/mcp-microsoft-todo.svg)](LICENSE)\n\n---\n\n## 🏗 Built and maintained by MAG&Cie\n\nThis MCP server is open-source and free to use. It's also a showcase of our **Création de MCP** offering at [MAG&Cie](https://www.mag-cie.com) — we build custom MCP connectors for businesses that want to plug AI into their internal tools (CRM, ERP, custom APIs, internal databases).\n\nIf you'd like the same kind of connector for **your** tools — drop us a line at [www.mag-cie.com/creation-mcp](https://www.mag-cie.com/creation-mcp).\n\n---\n\n## 🚀 End-user installation\n\n### Prerequisites (all clients)\n\n- **Node.js 20+** ([nodejs.org](https://nodejs.org))\n- A Microsoft account (free or paid)\n\nNo Azure account required, no App Registration to create, nothing to compile.\n\n---\n\n### 🟦 Claude Code (CLI)\n\n**Install (one command):**\n\n```bash\nclaude mcp add --transport stdio microsoft-todo -- npx -y @mag-cie/mcp-microsoft-todo\n```\n\nIf you have a **personal Microsoft account** (outlook.com, hotmail.com, live.com, msn.com, Office 365 personal), add `MS_TENANT=consumers`:\n\n```bash\nclaude mcp add --transport stdio microsoft-todo --env MS_TENANT=consumers -- npx -y @mag-cie/mcp-microsoft-todo\n```\n\n**Verify it's wired up:**\n\n```bash\nclaude mcp list\n```\n\n**First 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):\n\n```bash\n# macOS / Linux\nMS_TENANT=consumers npx -y @mag-cie/mcp-microsoft-todo@latest --auth\n```\n\n```powershell\n# Windows PowerShell\n$env:MS_TENANT=\"consumers\"; npx -y @mag-cie/mcp-microsoft-todo@latest --auth\n```\n\nYou'll see:\n```\nTo sign in, use a web browser to open the page https://www.microsoft.com/link and enter the code XXXXXXXXX\n```\n\nVisit 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.\n\n> 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).\n\n**Update to the latest version:**\n\n```bash\nclaude mcp remove microsoft-todo\nclaude mcp add --transport stdio microsoft-todo -- npx -y @mag-cie/mcp-microsoft-todo@latest\n```\n\nThe `-y` flag of npx auto-accepts the download. Without `@latest`, npx may serve a stale cached version.\n\n**Uninstall:**\n\n```bash\nclaude mcp remove microsoft-todo\n# Purge the token cache:\nrm -rf ~/.mcp-microsoft-todo\n```\n\n---\n\n### 🟪 Claude Desktop (app)\n\n**1. Locate the config file:**\n\n| OS | Path |\n|---|---|\n| **Windows** | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| **Linux** | `~/.config/Claude/claude_desktop_config.json` |\n\nOn Windows, you can open it directly with:\n```powershell\nnotepad $env:APPDATA\\Claude\\claude_desktop_config.json\n```\n\nIf the file doesn't exist, create it with an empty JSON object `{}` then edit.\n\n**2. Add the config:**\n\n```json\n{\n  \"mcpServers\": {\n    \"microsoft-todo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mag-cie/mcp-microsoft-todo\"]\n    }\n  }\n}\n```\n\nFor a personal Microsoft account, add `env`:\n\n```json\n{\n  \"mcpServers\": {\n    \"microsoft-todo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mag-cie/mcp-microsoft-todo\"],\n      \"env\": { \"MS_TENANT\": \"consumers\" }\n    }\n  }\n}\n```\n\nTo localize the compact-format strings (optional, see [Localization](#-localization)):\n\n```json\n{\n  \"env\": { \"MS_TENANT\": \"consumers\", \"MCP_LOCALE\": \"fr\" }\n}\n```\n\n**3. Restart Claude Desktop COMPLETELY** (not just close the window):\n- **Windows**: right-click systray icon → Quit, then relaunch\n- **macOS**: ⌘+Q then relaunch\n\n**4. Verify it's wired up:**\n\nIn Claude Desktop, look at the **🔌 plug** or **🔧 tools** icon at the bottom right of the input area — you should see `microsoft-todo` listed.\n\n**5. First auth — recommended pre-auth in a terminal:**\n\n```bash\n# macOS / Linux\nMS_TENANT=consumers npx -y @mag-cie/mcp-microsoft-todo@latest --auth\n```\n\n```powershell\n# Windows PowerShell\n$env:MS_TENANT=\"consumers\"; npx -y @mag-cie/mcp-microsoft-todo@latest --auth\n```\n\nYou'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.\n\nWithout `--auth`, the device code goes to the Claude Desktop MCP log file:\n- **Windows**: `%APPDATA%\\Claude\\logs\\mcp-server-microsoft-todo.log`\n- **macOS**: `~/Library/Logs/Claude/mcp-server-microsoft-todo.log`\n\n**Update:** edit the version in args (`@mag-cie/mcp-microsoft-todo@latest`), restart Claude Desktop. Or let npx do its thing (npx cache ~24h).\n\n---\n\n### 🟧 Cursor / Continue / other stdio MCP clients\n\nAny MCP client that supports the **stdio** transport works the same way. Generic format:\n\n```\ncommand: npx\nargs: -y @mag-cie/mcp-microsoft-todo\nenv: MS_TENANT=consumers (if personal account)\n```\n\nAdapt to the client's config format (often JSON or TOML similar to Claude Desktop).\n\n---\n\n## 💡 Example prompts\n\nOnce installed, just ask Claude in natural language. Sample prompts that exercise the main tools:\n\n| Prompt | Tool(s) |\n|---|---|\n| *\"Show me all my To Do lists\"* | `list_task_lists` |\n| *\"What do I have to do today?\"* | `summarize_today` |\n| *\"Show me my overdue tasks\"* | `list_overdue_tasks` |\n| *\"List tasks tagged 'work'\"* | `list_tasks_by_category` |\n| *\"Find any task containing 'invoice'\"* | `search_tasks` |\n| *\"Add a daily recurring 'Workout' task\"* | `create_task` (with recurrence) |\n| *\"Mark these 5 tasks as done\"* | `batch_complete_tasks` |\n| *\"Move 'Buy bread' from Personal to Shopping\"* | `move_task` |\n| *\"Add a 'recipe' subtask to the cake task\"* | `create_checklist_item` |\n| *\"Tag all my Magaria tasks as 'urgent'\"* | `bulk_update_categories` |\n| *\"Export my work tasks as iCalendar\"* | `export_tasks_ics` |\n| *\"Attach a project_id metadata to this task\"* | `set_extension` |\n\n---\n\n## 🆘 Auth troubleshooting\n\n| Symptom | Solution |\n|---|---|\n| \"This page isn't right\" page after sign-in | Add `MS_TENANT=consumers` (personal accounts only) |\n| Browser opens with the wrong Microsoft account | Use an **InPrivate/Incognito** window for the sign-in |\n| `invalid_scope` or `Tasks.ReadWrite.Shared` error | Purge the token cache and re-auth: `rm -rf ~/.mcp-microsoft-todo` |\n| `Node.js not found` or `npx not found` | Install Node 20+ from [nodejs.org](https://nodejs.org). On Windows, verify it's in PATH (relaunch your terminal after install) |\n| Token expired, refresh fails | Purge the cache and re-auth |\n| Device code never appears | Verify the server is spawning — Claude Code: `claude mcp list`; Claude Desktop: tools icon at the bottom. If absent, check the `npx` PATH in the config |\n| `MS_CLIENT_ID not configured` | You're using a dev fork — export `MS_CLIENT_ID` or use the official npm version |\n\n---\n\n## 🛠 Available tools (28)\n\nSafety column legend: `read` = read-only, `write` = mutates state (non-idempotent create), `update` = idempotent mutation (safe to retry), `delete` = destructive (data loss). See [Safety annotations](#-safety-annotations) below for details.\n\n### Lists & tasks\n| Tool | Safety | Description |\n|---|---|---|\n| `list_task_lists` | read | All your To Do lists |\n| `list_tasks` | read | Tasks of a list (OData filter, `$orderby`, `paginate`) |\n| `get_task` | read | Detail of a task by ID |\n| `create_task` | write | Create a task (title, body, importance, due date, categories, **recurrence, reminder**) |\n| `update_task` | update | Update title, status, due date, recurrence, reminder… |\n| `complete_task` | update | Mark as completed |\n| `delete_task` | delete | Delete permanently |\n| `move_task` | delete | Move a task from one list to another (source task is deleted) |\n| `search_tasks` | read | Cross-list search by title |\n| `summarize_today` | read | Summary of tasks due today + overdue |\n| `list_all_tasks` | read | Every task across every list in one round-trip (uses Graph `$batch`) |\n\n### Batch operations (saves API calls)\n| Tool | Safety | Description |\n|---|---|---|\n| `batch_create_tasks` | write | Create up to 100 tasks in a single Graph `$batch` HTTP call |\n| `batch_complete_tasks` | update | Mark up to 100 tasks as completed in one call |\n| `batch_delete_tasks` | delete | Delete up to 100 tasks in one call |\n\n### Sub-tasks (checklist items)\n| Tool | Safety | Description |\n|---|---|---|\n| `list_checklist_items` | read | Sub-items of a task |\n| `create_checklist_item` | write | Add a sub-item |\n| `update_checklist_item` | update | Rename / check / uncheck |\n| `delete_checklist_item` | delete | Delete a sub-item |\n\n### Linked resources (external URLs attached to a task)\n| Tool | Safety | Description |\n|---|---|---|\n| `list_linked_resources` | read | List the linked resources of a task |\n| `create_linked_resource` | write | Attach a URL or external reference |\n| `delete_linked_resource` | delete | Delete a linked resource |\n\n### Open extensions (custom JSON metadata)\n| Tool | Safety | Description |\n|---|---|---|\n| `list_extensions` | read | List the open extensions of a task |\n| `set_extension` | update | Upsert: create or update an extension (project_id, external_ref, etc.) |\n| `delete_extension` | delete | Delete an extension |\n\n### Cross-list helpers\n| Tool | Safety | Description |\n|---|---|---|\n| `list_overdue_tasks` | read | All overdue tasks, aggregated across all lists |\n| `list_tasks_by_category` | read | All tasks with a given category, cross-lists |\n| `bulk_update_categories` | update | Add/remove categories on many tasks in 2 batch phases |\n\n### Export\n| Tool | Safety | Description |\n|---|---|---|\n| `export_tasks_ics` | read | iCalendar export (VTODO + RRULE + VALARM) for import into Google Cal / Apple Cal / Outlook / Thunderbird |\n\n### Output format\n\nBy default, tools return a **compact text format** (one line per item) to save LLM tokens. Legend:\n- `[!]` high importance, `[?]` low (nothing if normal)\n- `[v]` completed, `[>]` in progress, `[w]` waiting, `[d]` deferred (nothing if not started)\n- `due:`, `rem:`, `rec:`, `cat:`, `body:` fields shown only when populated\n\nTo get the **full Graph JSON**, pass `verbose: true` to any read tool.\n\n---\n\n## 🔐 Safety annotations\n\nEvery tool exposed by this server carries the [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) defined by the Model Context Protocol spec (2025-06-18):\n\n| Annotation | Meaning |\n|---|---|\n| `readOnlyHint` | The tool only fetches data; running it has no side effects on Microsoft Graph |\n| `destructiveHint` | The tool deletes data or otherwise causes data loss that cannot be undone |\n| `idempotentHint` | Running the tool repeatedly with the same arguments yields the same end state (safe to retry) |\n| `openWorldHint` | The tool talks to an external system (Microsoft Graph) — always `true` here |\n| `title` | Human-readable display name for MCP clients |\n\nThese hints are **advisory** — the server itself enforces nothing — but MCP clients (Claude Code, Claude Desktop, Cursor, …) can use them to:\n\n- Auto-approve `readOnlyHint: true` calls without prompting (faster UX for read-heavy workflows)\n- Show a confirmation dialog before `destructiveHint: true` calls (e.g. `delete_task`, `batch_delete_tasks`, `move_task`)\n- Retry on transient failures only when `idempotentHint: true`\n- Display the friendly `title` instead of the snake_case `name`\n\nThe full mapping is in [`src/index.ts`](src/index.ts) (`ANNOTATIONS` constant). Summary by safety class (see also the per-tool **Safety** column above):\n\n- **read** (15 tools): all `list_*`, `get_*`, `search_*`, `summarize_*`, `export_*` — `readOnlyHint: true`\n- **write** (4 tools): `create_*`, `batch_create_tasks` — `destructiveHint: false, idempotentHint: false`\n- **update** (5 tools): `update_*`, `complete_*`, `set_extension`, `bulk_update_categories`, `batch_complete_tasks` — `destructiveHint: false, idempotentHint: true`\n- **delete** (5 tools): `delete_*`, `batch_delete_tasks`, `move_task` — `destructiveHint: true, idempotentHint: true`\n\n`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).\n\n---\n\n## 🌍 Localization\n\nThe 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.\n\nOptionally, 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:\n\n| Locale | Code |\n|---|---|\n| English (default) | `en` |\n| Français | `fr` |\n| Español | `es` |\n| Deutsch | `de` |\n\nResolution 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`.\n\n```json\n{\n  \"mcpServers\": {\n    \"microsoft-todo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mag-cie/mcp-microsoft-todo\"],\n      \"env\": { \"MCP_LOCALE\": \"fr\" }\n    }\n  }\n}\n```\n\n---\n\n## 🔒 Security & privacy\n\n- The Microsoft token is stored **only on your machine** in `~/.mcp-microsoft-todo/token-cache.json`\n- No data transits through MAG&Cie servers\n- Revoke access at any time at https://account.live.com/consent/Manage\n- To purge the local token: `rm -rf ~/.mcp-microsoft-todo`\n\nGraph permissions requested: `Tasks.ReadWrite`, `Tasks.ReadWrite.Shared`, `offline_access`.\n\n---\n\n## 🧑‍💻 Developer setup (fork / contribution)\n\nIf you fork or want to develop locally with your own Azure AD App Registration:\n\n### 1. Azure AD App Registration (maintainer/fork side only)\n\n1. https://portal.azure.com → **Microsoft Entra ID** → **App registrations** → **New registration**\n2. Name: `mcp-microsoft-todo` (free choice)\n3. Supported account types: **Accounts in any organizational directory and personal Microsoft accounts**\n4. Redirect URI: leave empty\n5. Register\n6. Note the **Application (client) ID**\n7. **Authentication** tab → **Allow public client flows**: **Yes**\n8. **Authentication** tab → **Add a platform** → **Mobile and desktop applications** → check `https://login.microsoftonline.com/common/oauth2/nativeclient`\n9. **API permissions** tab → **Add a permission** → **Microsoft Graph** → **Delegated** → add `Tasks.ReadWrite`, `Tasks.ReadWrite.Shared`, and `offline_access`. **Grant admin consent** if on a corporate tenant.\n\n### 2. Build and local auth\n\n```bash\ngit clone https://github.com/MAG-Cie/mcp-microsoft-todo\ncd mcp-microsoft-todo\nnpm install\nnpm run build\nexport MS_CLIENT_ID=\"<your-client-id>\"   # PowerShell: $env:MS_CLIENT_ID=\"...\"\nexport MS_TENANT=\"common\"\nnpm run auth\n```\n\nThe token cache will be written to `~/.mcp-microsoft-todo/token-cache.json`.\n\n### 3. Wire up Claude Code (local build)\n\n```powershell\n# Windows PowerShell\n$env:MS_CLIENT_ID=\"<your-client-id>\"\nclaude mcp add --transport stdio microsoft-todo -- node \"C:\\path\\to\\mcp-microsoft-todo\\dist\\index.js\"\n```\n\n```bash\n# macOS / Linux\nexport MS_CLIENT_ID=\"<your-client-id>\"\nclaude mcp add --transport stdio microsoft-todo -- node /path/to/mcp-microsoft-todo/dist/index.js\n```\n\n> ⚠️ Env vars must be visible at spawn time. On Windows with fnm, verify the PowerShell session that launches `claude` has `MS_CLIENT_ID` exported.\n\n### 4. Run tests\n\n```bash\nnpm test           # one-shot\nnpm run test:watch # watch mode\n```\n\n---\n\n## ⬆️ Upgrading from earlier versions\n\n| From | To | Action required |\n|---|---|---|\n| `0.x` | `0.4.0+` | Re-auth required: token cache lacks the new `Tasks.ReadWrite.Shared` scope. Run `rm -rf ~/.mcp-microsoft-todo` then trigger any tool to re-auth via device code. |\n| `0.x` | `0.5.0+` | No breaking change — new tools added. Token compatible. |\n| any | `1.0.0+` | Stable API marker. Future minor versions guarantee no breaking change to tool names, args, or return formats (compact + verbose). |\n\n---\n\n## 🗺 Roadmap\n\n- [x] v0.1 — stdio + 6 CRUD tools\n- [x] v0.2 — distributable npm package, baked-in client ID\n- [x] v0.3 — recurrence + reminders + checklists + linkedResources + search + move + summarize_today + retry/error robustness + vitest tests + compact format (verbose opt-in)\n- [x] v0.4 — auto pagination + `$batch` operations + `Tasks.ReadWrite.Shared` scope (read shared lists)\n- [x] v0.5 — open extensions + cross-list helpers (overdue, by category, bulk update) + iCalendar export\n- [x] v1.0 — stable milestone: GitHub Actions CI + extended tests + snapshot tests + README polish\n\nPossible future versions:\n- v1.1 — file attachments (Graph beta)\n- v1.2 — auto-pagination follow-on for `summarize_today` / `search_tasks` / `list_overdue_tasks`\n- v2.0 — remote HTTP/SSE transport for Claude.ai custom connectors (multi-user OAuth)\n\n---\n\n## 📄 License\n\n[MIT](LICENSE) — © MAG&Cie\n",
  "bytes": 17749,
  "sha": "3009ac3bf706de94e365dbc117ae1787e33c9d08199d80307b92b1bd621db5d0",
  "repo_slug": "mag-cie/mcp-microsoft-todo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mag_cie_mcp_microsoft_todo_eaf8b454/readme"
}