Microsoft Todo MCP Server

Microsoft To Do MCP

A Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor to interact with Microsoft To Do via the Microsoft Graph API. This service provides comprehensive task management capabilities through a secure OAuth 2.0 authentication flow.

Just want to try it? Use Agent Todo

Running this server yourself means registering an app in Azure and managing its client secret. If you'd rather skip that, Agent Todo is a hosted MCP server that supports Microsoft To Do, from the same maintainer. You sign in to Agent Todo, connect your Microsoft To Do account on its Connections page, then add the connector to your AI assistant. There's nothing to register or install.

• Free plan: one connected task provider, such as Microsoft To Do, with read and write access.
• Pro plan: every provider (Google Tasks and Todoist too), with sync between them.

Connect it from any MCP client that supports remote servers. It signs you in with OAuth on first use.

# Claude Code

claude mcp add --transport http agent-todo https://api.agent-gate.com/agent-todo/mcp

In Claude Desktop or claude.ai, open Settings, then Connectors, and add https://api.agent-gate.com/agent-todo/mcp as a custom connector.

Want to run it on your own machine, or keep your tokens local? Keep reading to set up this server.

Features

• 17 MCP Tools: Complete task management functionality including lists, tasks, checklist items, and organization features
• Recurring Tasks: First-class support for Microsoft Graph recurrence (daily / weekly / absoluteMonthly / relativeMonthly / absoluteYearly / relativeYearly) on create-task and update-task
• OAuth 2.0 Authentication: Sign in once; tokens renew automatically
• Microsoft Graph API Integration: Direct integration with Microsoft's official API
• Multi-tenant Support: Works with personal, work, and school Microsoft accounts
• Built on [somamcp](https://www.npmjs.com/package/somamcp): MCP SDK 2.x underneath, served over stdio
• TypeScript: Fully typed for reliability and developer experience
• ESM Modules: Modern JavaScript module system

Prerequisites

• Node.js 20 or higher (CI tests 22.x and 24.x); building from source needs 22.18 or higher, or 24.11 or higher
• pnpm, only to build from source
• A Microsoft account (personal, work, or school)
• Azure App Registration (see setup below)

Installation

Option 1: Global Installation (Recommended)

# Install globally using npm

npm install -g microsoft-todo-mcp-server

Or using pnpm

pnpm install -g microsoft-todo-mcp-server

Or run directly with npx (no installation)

npx microsoft-todo-mcp-server

The package provides four commands:

• microsoft-todo-mcp-server - The MCP server
• mstodo - Short alias for the MCP server
• mstodo-config - Writes an mcp.json from tokens.json (see Step 3 for a caveat)
• mstodo-setup - Guided setup. It does not yet finish on its own after you sign in, so use the steps under Usage instead

Option 2: Clone and Run Locally

git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git

cd microsoft-todo-mcp-server pnpm install pnpm run build

Azure App Registration

1. Go to the Azure Portal
2. Navigate to "App registrations" and create a new registration
3. Name your application (e.g., "To Do MCP")
4. For "Supported account types", select one of the following based on your needs:

• Accounts in this organizational directory only (Single tenant) - For use within a single organization
• Accounts in any organizational directory (Any Azure AD directory - Multitenant) - For use across multiple organizations
• Accounts in any organizational directory and personal Microsoft accounts - For both work accounts and personal accounts

1. Add a Web platform redirect URI: http://localhost:3000/callback
2. After creating the app, go to "Certificates & secrets" and create a new client secret. Note when it expires: sign-in and token renewal stop working on that date
3. Go to "API permissions" and add these Microsoft Graph delegated permissions. The sign-in requests these (plus the standard openid and profile), so adding them here is what lets an admin approve them ahead of time:

• Tasks.Read, Tasks.ReadWrite, Tasks.Read.Shared, Tasks.ReadWrite.Shared
• User.Read, offline_access

1. For a work or school tenant that requires it, an admin clicks "Grant admin consent". Personal accounts consent on the sign-in page

Configuration

Environment Setup

Create a .env file in the repository root, where you run pnpm run auth (required for sign-in):

CLIENT_ID=your_client_id

CLIENT_SECRET=your_client_secret TENANT_ID=your_tenant_setting REDIRECT_URI=http://localhost:3000/callback

TENANT_ID Options

• organizations - For multi-tenant organizational accounts (the default when TENANT_ID is unset)
• consumers - For personal Microsoft accounts only
• common - For both organizational and personal accounts
• your-specific-tenant-id - For single-tenant configurations

Examples:

# For multi-tenant organizational accounts (default)

TENANT_ID=organizations

For personal Microsoft accounts

TENANT_ID=consumers

For both organizational and personal accounts

TENANT_ID=common

For a specific organization tenant

TENANT_ID=00000000-0000-0000-0000-000000000000

Token Storage

The server stores authentication tokens in tokens.json. It looks in three places, in order:

1. MSTODO_TOKEN_FILE, if set
2. the per-user config directory — ~/.config/microsoft-todo-mcp/tokens.json, or %APPDATA%\microsoft-todo-mcp\tokens.json on Windows
3. tokens.json in the working directory, which is migrated to whichever of (1) or (2) is in effect on first read

# Override the location

export MSTODO_TOKEN_FILE=/path/to/custom/tokens.json

You can also supply tokens directly, which takes precedence over the file:

export MS_TODO_ACCESS_TOKEN=your_access_token

export MS_TODO_REFRESH_TOKEN=your_refresh_token

These two are a starting point, not a live store — nothing rewrites your environment when a token is renewed. A renewal is kept for the rest of the session and written to the token file, and the environment pair is not consulted again.

How the expiry is known depends on your account type. Work and school accounts get a JWT access token, so the server reads the real deadline from it and renews 5 minutes early. Personal accounts get an opaque token, where there is nothing to read and the server assumes an hour from when it first saw the value. Either way renewal needs CLIENT_ID and CLIENT_SECRET; without them the server cannot refresh, and calls start failing once the supplied token runs out.

Usage

Complete Setup Workflow

Step 1: Sign in with Microsoft

Sign-in runs from a clone of this repository, with the .env file from Configuration in its root:

git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git

cd microsoft-todo-mcp-server pnpm install pnpm run build pnpm run auth

Open http://localhost:3000 and sign in. Microsoft sends you back to /callback, and the server writes tokens.json in the repository root. Stop it with Ctrl+C when the page says authentication succeeded.

Step 2: Move the tokens where the server looks

tokens.json holds your refresh token and your client secret, so keep it private:

# macOS and Linux

mkdir -p ~/.config/microsoft-todo-mcp mv tokens.json ~/.config/microsoft-todo-mcp/tokens.json chmod 600 ~/.config/microsoft-todo-mcp/tokens.json

On Windows, move it to %APPDATA%\microsoft-todo-mcp\tokens.json. To keep it elsewhere, set MSTODO_TOKEN_FILE to its path in the next step.

Step 3: Configure Your AI Assistant

The server finds the token file itself and renews tokens with the client credentials stored in it, so the config needs no secrets.

Claude Code:

claude mcp add -s user microsoft-todo -- npx -y microsoft-todo-mcp-server

Token file somewhere else:

claude mcp add -s user microsoft-todo -e MSTODO_TOKEN_FILE=/path/to/tokens.json -- npx -y microsoft-todo-mcp-server

-s user makes it available in every project; without it, Claude Code adds it only to the folder you ran the command in.

Claude Desktop: add this to its config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{

"mcpServers": { "microsoftTodo": { "command": "npx", "args": ["--yes", "microsoft-todo-mcp-server"] } } }

Add "env": { "MSTODO_TOKEN_FILE": "/path/to/tokens.json" } if the file is not in the default location.

Cursor: add the same mcpServers entry to ~/.cursor/mcp.json.

About `mstodo-config` and token environment variables: pnpm run create-config (or mstodo-config) writes an mcp.json that passes MS_TODO_ACCESS_TOKEN and MS_TODO_REFRESH_TOKEN instead of a token file. Renewing those also needs CLIENT_ID and CLIENT_SECRET in the same env block, plus TENANT_ID unless it is organizations. Without them, calls start failing when the access token expires, within about an hour of signing in. The token-file setup above avoids this.

Available Scripts

# Development & Building

pnpm run build # Build TypeScript to JavaScript pnpm run dev # Build and run CLI in one command pnpm run validate # Format, lint, typecheck, test and build pnpm test # Run the tests

Running the Server

pnpm start # Run MCP server directly pnpm run cli # Run MCP server via CLI wrapper npx microsoft-todo-mcp-server # Run globally installed version

Authentication & Configuration

pnpm run auth # Start OAuth authentication server pnpm run create-config # Generate mcp.json from tokens.json

Code Quality

pnpm run format # Format code with Prettier pnpm run format:check # Check code formatting pnpm run lint # Run linting checks pnpm run typecheck # TypeScript type checking

MCP Tools

The server provides 17 tools for comprehensive Microsoft To Do management:

Authentication and Server Info

• `auth-status` - Check authentication status, token expiration, and account type
• `info` - Report the server's name, version, build, runtime, and tool count (from somamcp; build details come from the SOMAMCP_BUILD_COMMIT, SOMAMCP_BUILD_DATE, SOMAMCP_BUILD_BRANCH and SOMAMCP_ENVIRONMENT environment variables when set)

Task Lists (Top-level Containers)

• `get-task-lists` - Retrieve all task lists with metadata (default, shared, etc.)
• `create-task-list` - Create a new task list
• `update-task-list` - Rename an existing task list
• `delete-task-list` - Delete a task list and all its contents
• `get-task-lists-organized` - Group task lists into folders by naming pattern, emoji prefix, or sharing status (groupBy: category, shared, or type; includeIds adds an ID reference)

Tasks (Main Todo Items)

• `get-tasks` - Get tasks from a list with filtering, sorting, and pagination
• Supports OData query parameters: $filter, $orderby, $top, $skip, $count
• orderby works on date fields such as createdDateTime; Graph rejects orderby=title
• top caps the total,