Skip to main content
Glama

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-mcp backup 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).

  1. Download the .dmg from Releases, open it, and drag To Do MCP onto the Applications shortcut.

  2. 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).

  3. 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 overwrite

DeepSeek 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-in

Connect 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-mcp

Install 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 Harness

For 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-keepalive

The 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

list_lists, create_list, rename_list, delete_list

Lists

list_tasks

Tasks in a list: status open/completed/all, title_contains, include_steps, limit (newest first)

get_task

One task in full: note, steps (with tick times), dates, reminder (even when switched off), importance, repeat rule, linked emails, attachment names and sizes

create_task, update_task, delete_task

Title, note, due date, reminder, importance, completion; create_task can add steps

add_step, update_step, delete_step

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 one

  • MSTODO_AUTHORITY: default https://login.microsoftonline.com/consumers (personal accounts); use .../organizations for work accounts

  • MSTODO_TIMEZONE: IANA zone, default is the system zone

  • MSTODO_CACHE: token cache path

License

MIT, see LICENSE.

Available Tools

12 tools
add_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_listA
DestructiveIdempotent

Permanently delete a To Do list and every task in it (no recycle bin). Confirm with the user first.

Inputs: list (required).

delete_stepA
DestructiveIdempotent

Delete a step from a task.

Inputs: list (required), step_id (required), task_id (required).

delete_taskA
DestructiveIdempotent

Permanently delete a task (no recycle bin). To finish a task, use update_task(completed=true) instead.

Inputs: list (required), task_id (required).

get_taskA
Read-only

Get one task in full: note, steps, dates, repeat rule, linked items and attachment names.

Inputs: list (required), task_id (required).

list_listsA
Read-only

List all To Do lists (including the default 'Tasks' list and 'Flagged Emails').

Inputs: no named parameters.

list_tasksA
Read-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_listB
DestructiveIdempotent

Rename a To Do list.

Inputs: list (required), new_name (required).

update_stepB
DestructiveIdempotent

Rename a step or tick/untick it.

Inputs: list (required), step_id (required), task_id (required), text, +1 more.

update_taskA
DestructiveIdempotent

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

    A3.7/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers