To Do & Planner MCP server

A local MCP server that lets Claude (Desktop chats, Projects and Cowork, or Claude Code) create, read, update and delete Microsoft To Do and Microsoft Planner items through Microsoft Graph, as the signed-in user.

Lists, plans and buckets can be referenced by ID or exact name (ambiguous names are rejected, never guessed). Delete tools are marked destructive so Claude asks before running them.

Scope note: Graph exposes basic Planner plans. Planner Premium / Project for the web "projects" are Dataverse-based and are not reachable through these Graph endpoints.

Quick install (any Windows machine with Claude)

Pick one method per machine. Installing both gives you duplicate tools.

Option A: Claude Desktop extension (.mcpb), no terminal needed after uv is installed

1. Install uv once. It's per-user, needs no admin rights and isn't an MSI:

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Download todo-planner-<version>.mcpb from this repo's Releases page, or build it yourself (see below).

3. Double-click the file, or go to Claude Desktop → Settings → Extensions and drag the file in. Review the optional settings (tenant, time zone, auto sign-in) and click Install.

4. In any chat, Project or Cowork task, say "Log in to To Do". Claude asks which sign-in option you want and opens your browser.

The first start takes a little longer while uv downloads Python and the pinned dependencies. Extension settings can be changed later under Settings → Extensions.

Option B: install.ps1, also works for Claude Code and Intune

From a normal PowerShell or Windows Terminal window (not a terminal inside Claude), in a copy of this repo:

powershell -ExecutionPolicy Bypass -File .\install.ps1

The script installs uv if it's missing (it asks first), installs Python and the pinned dependencies, runs the sign-in menu (option 1 or 2), registers the server with Claude Desktop (asking you to quit Claude first) and verifies everything. Useful switches:

For an Intune Win32 app, run install.ps1 -SkipLogin -Yes in the user context. Each user then says "Log in to To Do" in Claude.

Building the .mcpb

uv run python scripts\build_mcpb.py --schema path\to\mcpb-manifest-v0.4.schema.json

This generates manifest.json from the live tool list and pyproject.toml, validates it against the official MCPB schema when --schema is given (needs uv run --with jsonschema), and writes dist/todo-planner-<version>.mcpb. The bundle is built from an explicit allow-list: source, pyproject.toml, uv.lock, README and icon. It never contains .venv, settings or tokens. Dependencies are installed with --frozen from uv.lock.

Related MCP server: Planner MCP Server

Security design

• Delegated permissions only – everything runs as you; you can only touch lists/plans you already have access to.

• No secrets – public client (no client secret or certificate). Only the client ID, tenant and time zone are saved, and none of them are secrets.

• Encrypted token cache – MSAL tokens are stored with msal-extensions, encrypted with Windows DPAPI under your user profile (%USERPROFILE%\.todo-planner-mcp\msal_token_cache.bin). Nothing is written to the repo.

• MFA / Conditional Access honoured – sign-in happens in the system browser against your tenant.

• Least privilege – default scopes are User.Read + Tasks.ReadWrite. Extra scopes are opt-in.

• Tokens only go to Graph: bearer tokens are only ever sent to https://graph.microsoft.com/v1.0/. The server checks the parsed scheme, host, port and path, so look-alike URLs are refused. Logs go to stderr and never contain tokens.

• Prompt-injection guard: task titles and notes in shared lists and plans are written by other people. Claude is told to treat them as data and never follow instructions inside them. The sign-in app and tenant can't be changed from chat once configured, only from the terminal or the extension settings, which blocks consent-phishing via injected text.

• Pinned dependencies: every launch uses uv … --frozen, so only the hash-pinned versions in uv.lock are installed.

Recommended settings

• In Claude, don't choose "Always allow" for the *_delete_* tools, so every delete still needs your click.

• With option 2, pin your tenant (--tenant yourdomain) rather than using organizations, especially if you also have accounts in customer tenants.

• Prefer option 1 (your own app registration) for managed or MSP use. You can then apply Conditional Access, assignment requirements and sign-in log filtering to it alone.

• The optional permissions (GroupMember.Read.All, User.ReadBasic.All, MailboxSettings.Read) are read-only. Only grant the ones you use.

Known limitations

• Anyone who can run code as your Windows user can use your cached session. That's the same trust boundary as Outlook and Teams; DPAPI protects the cache from other users and offline copies, not from malware running as you.

• planner_list_my_groups with GroupMember.Read.All returns all your group memberships to Claude.

• If uv is missing and winget isn't available, install.ps1 falls back to astral.sh's official install script (HTTPS, after asking you).

1. Choose how to sign in

At login you pick one of two options:

With option 2, pin your own domain if you also hold accounts in customer tenants. That stops you signing in to a customer tenant by mistake.

Registering your own app (option 1 only, about 5 min)

1. Entra admin center → Identity → Applications → App registrations → New registration

   • Name: Claude To Do Planner MCP

   • Supported account types: Single tenant

   • Redirect URI: platform Public client/native (mobile & desktop), value http://localhost

2. API permissions → Add a permission → Microsoft Graph → Delegated:

   • User.Read, Tasks.ReadWrite (required)

   • Optional: GroupMember.Read.All (lets planner_list_my_groups list groups for new plans – admin consent needed)

   • Optional: User.ReadBasic.All (lets you assign Planner tasks to people by email)

3. Click Grant admin consent (recommended for a managed tenant so users aren't prompted).

4. Do not create a client secret. Leave "Allow public client flows" = No.

5. Copy the Application (client) ID and Directory (tenant) ID (or use your verified domain).

2. Install

Requires uv (it installs Python for you).

cd C:\Github\ToDo-MCP
uv sync

3. Sign in once

uv run todo-planner-mcp login

How do you want to sign in to Microsoft 365?
  1. Own app registration (your Entra client ID)
  2. Microsoft-published app (Microsoft Graph Command Line Tools, no registration)
Choose 1 or 2: 1
Application (client) ID: <guid>
Tenant ID or verified domain (e.g. contoso.com.au): contoso.com.au
Time zone ('auto' = detect from Microsoft 365, or e.g. Australia/Sydney) [auto]:

Your browser opens for sign-in and MFA. The choice is saved, without secrets, to %USERPROFILE%\.todo-planner-mcp\settings.json. Tokens are kept in a separate DPAPI-encrypted cache and refresh silently. Run login again to switch options; switching app or tenant clears the old tokens.

To skip the menu: uv run todo-planner-mcp login --app microsoft --tenant contoso.com.au --timezone Australia/Sydney (or --app own --client-id <guid> --tenant <tenant>). status and logout are also available.

You can also sign in from inside Claude. Ask it to "log in to To Do". Claude asks which option you want and then calls the login tool, which opens your browser.

Automatic sign-in when the session expires

You normally sign in once. MSAL refreshes tokens silently, and the refresh token lasts up to 90 days while you keep using it. The session can still end early: a Conditional Access sign-in frequency policy, a password change, revoked sessions or an admin action will all do it.

When that happens, the next request opens the Microsoft sign-in page in your browser automatically, pre-filled with your account. Complete sign-in and MFA, and the request carries on.

• Only one sign-in window opens, even if Claude is running several requests at once.

• If you close the window without signing in, it won't reopen for 2 minutes. Ask Claude to "log in to To Do" when you're ready.

• Status checks (auth_status, status) never open the browser.

• Turn it off or on with uv run todo-planner-mcp auto-login off|on, ask Claude to "turn off automatic sign-in", or set TODO_MCP_AUTO_LOGIN=off.

• If the window opens behind other windows, look for the browser flashing on the taskbar.

Time zone detection

Dates you type ("due Friday", "2026-11-01") are interpreted in your time zone. With the default auto setting, the server uses, in order:

1. Your Microsoft 365 time zone: the one in Outlook → Settings → Time zone, which To Do and Outlook also use. This needs the read-only MailboxSettings.Read permission. With option 2 it is requested at your next interactive sign-in. With option 1, add it to the app registration and to TODO_MCP_EXTRA_SCOPES. Until it's granted, nothing pops up; the server just uses the next source.

2. This computer's Windows time zone.

3. UTC.

Microsoft 365 reports Windows zone names (e.g. AUS Eastern Standard Time), which the server maps to IANA names (Australia/Sydney). To pin a zone instead, run login and enter it, or set TODO_MCP_TIMEZONE. Ask Claude "check my To Do sign-in status" to see which zone is in use and where it came from.

4. Add to Claude Desktop (Chat, Projects and Cowork)

1. Fully quit Claude Desktop (tray icon → right-click → Quit). Closing the window isn't enough. While the app is running it rewrites its config from memory and drops entries added in the meantime.

2. From a normal terminal, run:

   uv run --directory C:\Github\ToDo-MCP python scripts\register_claude_desktop.py

   The script finds the right config file, makes a timestamped backup and adds the entry below. The Store (MSIX) build of Claude Desktop keeps its config in %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\, not in %APPDATA%\Claude. To remove the entry later, add --remove.

3. Start Claude Desktop. The tools appear under the connectors/tools menu in any chat, Project or Cowork task.

The entry needs no IDs, because the server reads the saved login choice (see claude_desktop_config.example.json):

"mcpServers": {
  "todo-planner": {
    "command": "C:\\Users\\<you>\\.local\\bin\\uv.exe",
    "args": ["run", "--frozen", "--directory", "C:\\Github\\ToDo-MCP", "todo-planner-mcp"]
  }
}

For Claude Code instead:

claude mcp add todo-planner --scope user -- uv run --frozen --directory C:\Github\ToDo-MCP todo-planner-mcp

Configuration

The saved login choice is used by default. Environment variables override it, for example to enforce one app across a managed fleet. If TODO_MCP_CLIENT_ID is set, you can't choose the app at login.

Example prompts

Write naturally; you don't need tool names. Mentioning "To Do" or "Planner" helps Claude pick the right one. These examples are also in the server's description, so Claude sees them in every chat, Project and Cowork task.

Microsoft To Do (lists = projects)

Microsoft Planner (plans = projects)

Account

Combined: "Read my meeting notes below and create Planner tasks in M365 Migration – Contoso for every action item, assigned to me, due next week."

Validation checklist

1. uv run todo-planner-mcp status → shows your account, token valid.

2. In Claude: "check To Do auth status" → tokenValid: true.

3. Create → update → delete a test task in a scratch list; confirm each in the To Do app.

4. Same for a Planner task in a test plan.

Rollback

• Remove the todo-planner entry from claude_desktop_config.json and restart Claude.

• uv run todo-planner-mcp logout, then delete %USERPROFILE%\.todo-planner-mcp (saved choice and token cache).

• Delete the app registration in Entra ID to revoke all access; optionally revoke sessions for the user.

Troubleshooting