mstodo-mcp
MCP server for reading and editing Microsoft To Do (lists, tasks, steps) via Microsoft Graph, with agent integration, skills, and sign-in management.
List, create, rename, and delete To Do lists
List tasks with filters (status, title text, include steps, limit) and get full task details
Create tasks with title, note, due date, reminder, importance, and steps
Update tasks: title, note, due date, reminder, importance, mark complete/reopen, clear fields
Permanently delete tasks
Add, rename, tick/untick, and delete steps (subtasks)
Use display names (case-insensitive) or IDs for lists
Manage sign-in: login, status, logout, and keepalive to stay signed in
Run as a macOS menu-bar app or from source; connect to agents like Claude Code, Codex, Cursor, Gemini CLI, and Claude Desktop
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mstodo-mcp What tasks are due today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mstodo-mcp
MCP server for reading and editing Microsoft To Do through Microsoft Graph, plus an agent skill that teaches any AI agent (Claude Code, Codex, DeepSeek Harness, Gemini, Cursor, ...) how to use it well.
There are two ways to run it: the macOS menu-bar app (no Python or terminal needed), or from source on any OS with uv. Either way you need a Microsoft account with To Do.
macOS app
To Do MCP.app is a menu-bar app (macOS 13 or later) that bundles its own Python and the
server. From its menu you can:
sign in to Microsoft (the code is copied and the Microsoft page opens for you), and see whether the sign-in is still valid; it renews the sign-in daily while running and notifies you if you need to sign in again
Connect to Agent: register the server with Claude Code, Codex CLI, DeepSeek Harness, Claude Desktop, Cursor or Gemini CLI in one click (config files keep their other settings, and a
.bak-todo-mcpbackup is written first)Install Skill for Claude Code, Codex or DeepSeek Harness (an existing, different copy is moved to
skill-backups/, never deleted)turn on Launch at Login
Install
Requirements: macOS 13 or later on an Apple Silicon Mac (M1 or newer).
Download the
.dmgfrom Releases, open it, and drag To Do MCP onto the Applications shortcut.Open it from Applications (not from the disk image or Downloads; otherwise macOS runs it from a temporary location and connected agents lose track of it).
The first time, macOS blocks it (see below). After that, click the checklist icon in the menu bar → Sign In…, then Connect to Agent.
"Apple could not verify…": opening an unsigned app
The app is free and open source but not signed or notarized by Apple (that needs a paid Apple developer account), so Gatekeeper blocks the first launch. Only allow it if you downloaded it from this repository's Releases page, or built it yourself.
In System Settings: double-click the app and click Done when macOS refuses. Then open System Settings → Privacy & Security, scroll to Security, click Open Anyway next to the "To Do MCP" message, confirm with your password or Touch ID, and click Open Anyway again. You only do this once. (On macOS 15 and later, right-click → Open no longer skips this step.)
Or in Terminal: remove the "downloaded from the internet" flag, then open it normally:
xattr -dr com.apple.quarantine "/Applications/To Do MCP.app"
The same instructions are in READ ME FIRST.txt on the disk image. The app is ad-hoc signed,
so macOS can still check that its files haven't been changed since it was built.
Build it yourself
scripts/build-app.sh builds the app and the .dmg into dist/ (needs Swift, from Xcode or
the Command Line Tools, and uv). A build is for the building Mac's architecture, and an app
you build yourself isn't quarantined, so it opens without the steps above.
Inside the app, To Do MCP.app/Contents/MacOS/mstodo-mcp is the same CLI and server as below
(status, login, ...), and the app's own binary has a scriptable mode:
APP="/Applications/To Do MCP.app/Contents/MacOS"
"$APP/ToDoMCP" --diagnose # what's connected and installed
"$APP/ToDoMCP" --connect codex # claude-code, codex, dsh, claude-desktop, cursor, gemini
"$APP/ToDoMCP" --install-skill claude # claude, codex or dsh; add --replace to overwriteDeepSeek Harness (dsh) has no mcp add command; an MCP server is a row in a profile's
cordis.patch.yml. Connecting adds one marked block to the web profile (created by dsh if it
doesn't exist yet) and to the headless profile if you have one; other profiles are left alone.
The rest of the file, comments included, stays as it is. After writing, the app asks dsh to
compose the profile (dsh --profile web --dump-config) and puts the file back if dsh rejects it.
Disconnect removes only that block. A mstodo entry you wrote by hand is never edited; the app
tells you what to change instead. The skill goes to $DSH_HOME/skills (default ~/.dsh/skills).
Related MCP server: todo-mcp
Setup from source
git clone https://github.com/QingyaoAi/Microsoft-To-do-MCP.git
cd Microsoft-To-do-MCP
uv sync # install into .venv (Python 3.12, pinned by uv)
.venv/bin/mstodo-mcp login # one-time device-code sign-in in the browser
.venv/bin/mstodo-mcp status # check sign-inConnect it to your agent
The server is a local stdio program with no arguments: <repo>/.venv/bin/mstodo-mcp. Register
it under the name mstodo in whichever MCP client you use, for example:
# Claude Code
claude mcp add --scope user mstodo -- "$PWD/.venv/bin/mstodo-mcp"
# Codex CLI
codex mcp add mstodo -- "$PWD/.venv/bin/mstodo-mcp"Clients configured with an mcpServers JSON file (Claude Desktop, Cursor, Gemini CLI and
others) take the same command:
{
"mcpServers": {
"mstodo": { "command": "/absolute/path/to/repo/.venv/bin/mstodo-mcp" }
}
}For DeepSeek Harness (dsh) add this to the top-level array in
~/.dsh/profiles/web/cordis.patch.yml (or another profile's). The tools show up as
mcp__mstodo__<tool>:
- insert:
- id: mcp-mstodo
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: mstodo
transport: stdio
command: /absolute/path/to/repo/.venv/bin/mstodo-mcpInstall the skill (optional)
skills/ms-todo/SKILL.md teaches an agent to use the tools well: find tasks before editing,
ask when a name is ambiguous, handle dates, respect the limits, and cope with an expired
sign-in. It uses the open Agent Skills format (a folder with a SKILL.md), is written for any
MCP client, and doesn't assume Claude. Copy or symlink the folder into your agent's skills
directory, for example:
mkdir -p ~/.claude/skills && cp -r skills/ms-todo ~/.claude/skills/ # Claude Code
mkdir -p ~/.codex/skills && cp -r skills/ms-todo ~/.codex/skills/ # Codex CLI
mkdir -p ~/.dsh/skills && cp -r skills/ms-todo ~/.dsh/skills/ # DeepSeek HarnessFor other agents, see their documentation for the skills directory. For an agent without
skill support, paste the body of SKILL.md (everything after the front matter) into its
instructions file, such as AGENTS.md or GEMINI.md.
Sign-in uses Microsoft's public "Microsoft Graph Command Line Tools" app, so no Azure
registration is needed. The token cache lives in ~/.config/mstodo-mcp/token_cache.json
(mode 600) and refreshes itself. mstodo-mcp logout deletes it.
Staying signed in
Access tokens last about an hour and are renewed silently. The refresh token behind them expires after 90 days without use, or earlier if the Microsoft password changes or the app's access is removed at https://account.live.com/consent/Manage.
.venv/bin/mstodo-mcp install-keepalive # daily launchd job (10:00, and at login)
.venv/bin/mstodo-mcp uninstall-keepaliveThe job runs mstodo-mcp keepalive, which renews the refresh token so the 90-day window
never runs out. If sign-in is really needed, it shows a dialog; "Sign in" copies the code,
opens the Microsoft page and saves the new token once you finish. "Later" (or no answer
within 4 hours) reminds again on the next run. Offline runs just retry next time.
Log: ~/Library/Logs/mstodo-mcp-keepalive.log.
If a tool call finds the sign-in expired, the server starts a sign-in in the background and returns the link and code (also shown as a macOS notification), so no terminal is needed.
Tools
Tool | What it does |
| Lists |
| Tasks in a list: |
| One task in full: note, steps (with tick times), dates, reminder (even when switched off), importance, repeat rule, linked emails, attachment names and sizes |
| Title, note, due date, reminder, importance, completion; |
| Steps (subtasks) |
Lists can be named by display name (case-insensitive) or id. Dates are in the local
time zone: due dates YYYY-MM-DD, reminders YYYY-MM-DD HH:MM. In update_task,
clear=["note" | "due_date" | "reminder"] removes those fields.
Not supported yet: editing repeat rules, downloading or adding attachment files, and "My Day" (not in the Graph API).
Configuration (environment variables)
MSTODO_CLIENT_ID: use your own Azure app registration instead of Microsoft's public oneMSTODO_AUTHORITY: defaulthttps://login.microsoftonline.com/consumers(personal accounts); use.../organizationsfor work accountsMSTODO_TIMEZONE: IANA zone, default is the system zoneMSTODO_CACHE: token cache path
License
MIT, see LICENSE.
Available Tools
12 toolsadd_stepC
Add a step (subtask) to a task.
Inputs: list (required), text (required), task_id (required), checked.
create_listA
Create a new To Do list.
Inputs: name (required).
create_taskC
Create a task, optionally with a note, due date, reminder and steps.
Inputs: list (required), title (required), note, steps, +3 more.
delete_listADestructiveIdempotent
Permanently delete a To Do list and every task in it (no recycle bin). Confirm with the user first.
Inputs: list (required).
delete_stepADestructiveIdempotent
Delete a step from a task.
Inputs: list (required), step_id (required), task_id (required).
delete_taskADestructiveIdempotent
Permanently delete a task (no recycle bin). To finish a task, use update_task(completed=true) instead.
Inputs: list (required), task_id (required).
get_taskARead-only
Get one task in full: note, steps, dates, repeat rule, linked items and attachment names.
Inputs: list (required), task_id (required).
list_listsARead-only
List all To Do lists (including the default 'Tasks' list and 'Flagged Emails').
Inputs: no named parameters.
list_tasksARead-only
List tasks in a list, newest first. Finished tasks are hidden unless status is "completed" or "all". Notes longer than 200 characters are shortened; use get_task for the full task.
Inputs: list (required), limit, status, include_steps, +1 more.
rename_listBDestructiveIdempotent
Rename a To Do list.
Inputs: list (required), new_name (required).
update_stepBDestructiveIdempotent
Rename a step or tick/untick it.
Inputs: list (required), step_id (required), task_id (required), text, +1 more.
update_taskADestructiveIdempotent
Change a task. Only the fields you pass are changed; use clear to remove a note, due date or reminder.
Inputs: list (required), task_id (required), note, clear, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource and action: lists, tasks, and steps each have their own set of lifecycle operations. The descriptions clearly separate permanent deletion from completing a task, so there is no ambiguity between tools.
All tool names follow a consistent verb_noun pattern (list_lists, create_task, update_step, delete_list). Rename_list uses a semantically specific verb, but it still fits the same pattern as the rest, making the naming predictable.
Twelve tools is a well-scoped size for a To Do server covering lists, tasks, and steps. Each tool serves a concrete purpose with no redundant or overwhelming additions.
The server covers CRUD operations for lists, tasks, and steps, including fetching full task details and managing subtasks. A minor gap is no explicit way to move a task between lists, though this may be achievable via update_task depending on the underlying API.
Maintenance
Related MCP Connectors
AI-powered to-do list: add, list, complete and organise tasks across lists from any assistant.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
A graph-based task manager your agent can read and update: tasks, dependencies, blockers.
Read and manage To-do Calendar todos, schedules and tags from an AI agent.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables comprehensive Microsoft To Do task management through Microsoft Graph API with Entra ID OAuth authentication. Supports creating, updating, and managing todo lists, tasks, reminders, and due dates through natural language.-
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Microsoft To Do tasks via the Graph API, supporting multiple accounts, encrypted auth, and full CRUD operations.2-

graphdo-tsofficial
AlicenseAqualityDmaintenanceEnables AI agents to send emails and manage tasks in Microsoft To Do with scoped, low-risk access to Microsoft Graph.34 npm1MIT- AlicenseNot gradedqualityCmaintenanceEnables coding agents to manage Microsoft To Do lists and tasks through Microsoft Graph, with optional support for checklist items, linked resources, attachments, and delta synchronization.1MIT