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.

🚀 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-todo

If 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-todo

Verify it's wired up:

claude mcp list

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):

# 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 --auth

You'll see:

To sign in, use a web browser to open the page https://www.microsoft.com/link and enter the code XXXXXXXXX

Visit 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@latest

The -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:

On Windows, you can open it directly with:

notepad $env:APPDATA\Claude\claude_desktop_config.json

If 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 --auth

You'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.log

• macOS: ~/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:

🆘 Auth troubleshooting

🛠 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

Batch operations (saves API calls)

Sub-tasks (checklist items)

Linked resources (external URLs attached to a task)

Open extensions (custom JSON metadata)

Cross-list helpers

Export

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):

These hints are advisory — the server itself enforces nothing — but MCP clients (Claude Code, Claude Desktop, Cursor, …) can use them to:

• Auto-approve readOnlyHint: true calls without prompting (faster UX for read-heavy workflows)

• Show a confirmation dialog before destructiveHint: true calls (e.g. delete_task, batch_delete_tasks, move_task)

• Retry on transient failures only when idempotentHint: true

• Display the friendly title instead of the snake_case name

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: true

• write (4 tools): create_*, batch_create_tasks — destructiveHint: false, idempotentHint: false

• update (5 tools): update_*, complete_*, set_extension, bulk_update_categories, batch_complete_tasks — destructiveHint: false, idempotentHint: true

• delete (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:

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.json

• No 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)

1. https://portal.azure.com → Microsoft Entra ID → App registrations → New registration

2. Name: mcp-microsoft-todo (free choice)

3. Supported account types: Accounts in any organizational directory and personal Microsoft accounts

4. Redirect URI: leave empty

5. Register

6. Note the Application (client) ID

7. Authentication tab → Allow public client flows: Yes

8. Authentication tab → Add a platform → Mobile and desktop applications → check https://login.microsoftonline.com/common/oauth2/nativeclient

9. 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.

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 auth

The 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 claude has MS_CLIENT_ID exported.

4. Run tests

npm test           # one-shot
npm run test:watch # watch mode

⬆️ Upgrading from earlier versions

🗺 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 + $batch operations + Tasks.ReadWrite.Shared scope (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_tasks

• v2.0 — remote HTTP/SSE transport for Claude.ai custom connectors (multi-user OAuth)

📄 License

MIT — © MAG&Cie