ms-todo-mcp

Microsoft To Do MCP server

An MCP server that lets an LLM client (Claude Desktop, Cowork, etc.) read and manage your Microsoft To Do tasks through the Microsoft Graph To Do API.

It exposes seven tools:

| Tool | What it does | Write? | |------|--------------|:------:| | todo_list_lists | List your task lists | – | | todo_list_tasks | List tasks in a list (by id or name), optional status filter | – | | todo_create_task | Create a task (title, note, due date, importance) | ✓ | | todo_update_task | Update title / note / due date / importance / status | ✓ | | todo_complete_task | Mark a task completed | ✓ | | todo_delete_task | Delete a task (permanent) | ✓ | | todo_create_list | Create a new task list | ✓ |

How auth works

Microsoft Graph does not support application-only (daemon) permissions for creating or updating To Do tasks — only delegated permissions work. This server therefore signs in as you using the OAuth2 device-code flow and caches the resulting access + refresh tokens on disk, so you only sign in once.

The token cache contains live credentials. It is written to ~/.ms_todo_mcp/token_cache.json by default and is git-ignored. Never commit it.

1. Register an app in Microsoft Entra ID

1. Entra admin center → App registrations → New registration.
2. Name it e.g. ms-todo-mcp. For Supported account types pick

Accounts in this organizational directory only (single tenant) unless you need broader access.

1. No redirect URI is required for the device-code flow. Click Register.
2. Authentication → Advanced settings → set

Allow public client flows = Yes (required for device-code).

1. API permissions → Add a permission → Microsoft Graph →

Delegated permissions → add Tasks.ReadWrite. If your tenant requires it, click Grant admin consent.

1. Copy the Application (client) ID and Directory (tenant) ID from the

app's Overview page.

2. Configure

cp .env.example .env
# edit .env and set MS_TODO_CLIENT_ID and MS_TODO_TENANT_ID

| Variable | Required | Notes | |----------|:--------:|-------| | MS_TODO_CLIENT_ID | ✓ | Application (client) ID | | MS_TODO_TENANT_ID | ✓ for work/school | Tenant ID/domain, or organizations / common | | MS_TODO_TOKEN_CACHE | – | Override token-cache path | | MS_TODO_TIMEZONE | – | IANA tz for due dates (default UTC) |

3. Install

Install the package into the Python interpreter your MCP client will launch. By default that is plain python on your PATH. Because the client starts the server from its own working directory, the simplest, path-free setup is to install into that default interpreter — not a virtualenv:

pip install -e .          # from the repo root (use `pip install .` for non-editable)

On Windows this also places an ms-todo-mcp launcher in your Python Scripts\ folder.

Want isolation instead of a global install? Don't reach for a bare venv with the default config — "command": "python" won't see a venv package. Use pipx (pipx install .), which isolates the package and puts the ms-todo-mcp command on your PATH; then set "command": "ms-todo-mcp" in the config. (A manual venv also works, but only if the config points at that venv's python.exe by absolute path — see examples/README.md.)

4. Sign in once

ms-todo-mcp login

Follow the printed instructions: open the URL, enter the code, sign in. The token cache is then stored and reused.

5. Run

ms-todo-mcp            # stdio transport (for local MCP clients)
ms-todo-mcp --http     # streamable HTTP on :8000 (for remote use)

6. Add it to your MCP client

For a local stdio client (e.g. Claude Desktop / Cowork custom connector), add an entry like the following. A ready-to-edit copy lives at examples/claude_desktop_config.json and uses your default Python on PATH (no virtualenv path hardcoded):

{
  "mcpServers": {
    "ms-todo": {
      "command": "python",
      "args": ["-m", "ms_todo_mcp"],
      "env": {
        "MS_TODO_CLIENT_ID": "<your-client-id>",
        "MS_TODO_TENANT_ID": "<your-tenant-id>",
        "MS_TODO_TIMEZONE": "Europe/Madrid"
      }
    }
  }
}

Notes:

• The config file lives at %APPDATA%\Claude\claude_desktop_config.json (Windows)

or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). Restart the app after editing it.

• For python -m ms_todo_mcp to resolve, install the package into that default

Python — run pip install -e . (or pip install .) without an active virtualenv. If python isn't your launcher, use python3 or the absolute interpreter path. On Windows you can instead set "command": "ms-todo-mcp" (the console script in your Python Scripts folder).

• Run ms-todo-mcp login once first so the token cache exists before the

client launches the server (the device-code prompt goes to stderr, not chat).

• Credentials live in env here because the repo .env is not read when the

client starts the server (its working directory isn't the project).

Usage examples (what to ask your assistant)

• "List my To Do lists."
• "Show the unfinished tasks in my 'Tasks' list."
• "Add 'Send Microsoft invoices to Diego' to my Work list, due Friday, high importance."
• "Mark the task about UAT as completed."

Development

pip install -e ".[dev]"
ruff check .
python -m py_compile src/ms_todo_mcp/*.py

Project layout

ms-todo-mcp/
├── pyproject.toml
├── README.md
├── CONTRIBUTING.md
├── LICENSE                 # MIT
├── .env.example
├── .gitignore
├── examples/
│   ├── README.md
│   └── claude_desktop_config.json
└── src/
    └── ms_todo_mcp/
        ├── __init__.py
        ├── __main__.py
        ├── auth.py
        ├── graph.py
        └── server.py

Releases

Releases are automated with release-please. You do not create tags or GitHub releases by hand.

The version is derived from Conventional Commits. Because main is squash-merged, the PR title is what counts — prefix it accordingly:

• fix: ... → patch bump (0.1.0 → 0.1.1)
• feat: ... → minor bump (0.1.0 → 0.2.0)
• feat!: ... or a BREAKING CHANGE: footer → major bump (0.1.0 → 1.0.0)
• docs: ..., chore: ..., ci: ..., refactor: ... → no release

Flow:

1. Merge PRs into main using Conventional Commit titles.
2. release-please opens (and keeps updating) a release PR titled

chore: release X.Y.Z, bumping the version in pyproject.toml and src/ms_todo_mcp/__init__.py and updating CHANGELOG.md.

1. When you merge that release PR, release-please creates the vX.Y.Z git tag

and the GitHub Release with auto-generated notes.