todo-mcp

An MCP (Model Context Protocol) server that gives AI assistants access to Microsoft To Do via the Microsoft Graph API. Supports multiple accounts (personal and work), encrypted token storage, and all common task operations.

Features

• List task lists and tasks across any number of accounts

• Create, update, complete, and delete tasks

• Get all pending tasks across every list in one call

• Multi-account support (e.g. separate work and personal aliases)

• Refresh tokens stored encrypted with AES-256-GCM on disk

• Non-blocking device code authentication flow (URL returned immediately)

Prerequisites

• Node.js 18 or later

• An Azure app registration with the Microsoft Graph Tasks.Read, Tasks.ReadWrite, and offline_access delegated permissions (see below)

1. Create an Azure App Registration

1. Go to portal.azure.com → Microsoft Entra ID → App registrations → New registration

2. Name it anything (e.g. My Todo MCP)

3. Supported account types: choose "Accounts in any organizational directory and personal Microsoft accounts" (enables both work and personal accounts)

4. No redirect URI needed — click Register

5. Copy the Application (client) ID — you'll need it below

6. Go to API permissions → Add a permission → Microsoft Graph → Delegated

   • Add: Tasks.Read, Tasks.ReadWrite, offline_access

   • Click Grant admin consent (or users will be prompted on first sign-in)

7. Go to Authentication → Advanced settings → enable "Allow public client flows" (required for device code)

8. Go to Manifest → set "requestedAccessTokenVersion": 2 in the api section → Save

2. Install

git clone <repo-url> todo-mcp
cd todo-mcp
npm install

3. Configure

Option A — Claude Desktop / Cowork (claude_desktop_config.json)

Add this to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "todo-mcp": {
      "command": "node",
      "args": ["C:/path/to/todo-mcp/index.js"],
      "env": {
        "TODO_MCP_CLIENT_ID": "<your-client-id>",
        "TODO_MCP_MASTER_KEY": "<random-base64-key>"
      }
    }
  }
}

Generate a secure master key (PowerShell):

[System.Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))

Or on macOS/Linux:

openssl rand -base64 32

Option B — VS Code (.vscode/mcp.json)

The included .vscode/mcp.json prompts for the master key securely on first use. Set TODO_MCP_CLIENT_ID in your environment or add it to the env block.

4. Authenticate Accounts

Once the server is running, use the authenticate_account tool from your AI assistant. It returns a device code URL immediately:

authenticate_account(account="work", tenant_id="<your-org-tenant-id>")
authenticate_account(account="personal", tenant_id="consumers")

Go to the URL shown, enter the code, and sign in. The token is saved automatically in the background.

For personal Microsoft accounts (Outlook, Hotmail, Live), always pass tenant_id="consumers".
For work/school accounts, pass your organization's tenant ID (a UUID), or "organizations" to accept any.

Environment Variables

Available Tools

All data tools accept an optional account parameter to target a specific alias. If omitted, the default account is used.

Token Storage

Refresh tokens are stored in ~/.todo-mcp-config.json encrypted with AES-256-GCM using a key derived from TODO_MCP_MASTER_KEY. The file is created with mode 0600 (owner read/write only). Never commit this file.