Microsoft To Do MCP

Interact with Microsoft To Do using the Microsoft Graph API.

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.

- 15 MCP Tools: Complete task management functionality including lists, tasks, checklist items, and organization features
- Seamless Authentication: Automatic token refresh with zero manual intervention
- OAuth 2.0 Authentication: Secure authentication with automatic token refresh
- Microsoft Graph API Integration: Direct integration with Microsoft's official API
- Multi-tenant Support: Works with personal, work, and school Microsoft accounts
- TypeScript: Fully typed for reliability and developer experience
- ESM Modules: Modern JavaScript module system

- Node.js 16 or higher (tested with Node.js 18.x, 20.x, and 22.x)
- pnpm package manager
- A Microsoft account (personal, work, or school)
- Azure App Registration (see setup below)

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 three command aliases:

- microsoft-todo-mcp-server- Full package name
- mstodo- Short alias for the MCP server
- mstodo-config- Configuration helper tool

git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git cd microsoft-todo-mcp-server pnpm install pnpm run build

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

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

# 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

# Using environment variable export MSTODO_TOKEN_FILE=/path/to/custom/tokens.json # Or pass tokens directly export MS_TODO_ACCESS_TOKEN=your_access_token export MS_TODO_REFRESH_TOKEN=your_refresh_token

# If installed globally git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git cd microsoft-todo-mcp-server pnpm install pnpm run auth # Or if running locally pnpm run auth

# Generate MCP configuration file pnpm run create-config # Or use the global helper (if installed globally) mstodo-config

{ "mcpServers": { "microsoftTodo": { "command": "npx", "args": ["--yes", "microsoft-todo-mcp-server"], "env": { "MS_TODO_ACCESS_TOKEN": "your_access_token", "MS_TODO_REFRESH_TOKEN": "your_refresh_token" } } } }

# Copy to Cursor's global configuration cp mcp.json ~/.cursor/mcp-servers.json

# Development & Building pnpm run build # Build TypeScript to JavaScript pnpm run dev # Build and run CLI in one command # 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

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

- auth-status- Check authentication status, token expiration, and account type

- 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-tasks- Get tasks from a list with filtering, sorting, and pagination

- Supports OData query parameters:$filter,$select,$orderby,$top,$skip,$count

- Title, description, due date, start date, importance, reminders, status, categories

- get-checklist-items- Get subtasks for a specific task
- create-checklist-item- Add a new subtask to a task
- update-checklist-item- Update subtask text or completion status
- delete-checklist-item- Remove a specific subtask

- MCP Server(src/todo-index.ts) - Core server implementing the MCP protocol
- CLI Wrapper(src/cli.ts) - Executable entry point with token management
- Auth Server(src/auth-server.ts) - Express server for OAuth 2.0 flow
- Config Generator(src/create-mcp-config.ts) - Helper to create MCP configurations

- Microsoft Graph API: Uses v1.0 endpoints
- Authentication: MSAL (Microsoft Authentication Library) with PKCE flow
- Token Management: Automatic refresh 5 minutes before expiration
- Build System: ts-builds (tsdown) for fast TypeScript compilation
- Module System: ESM (ECMAScript modules)

- MailboxNotEnabledForRESTAPI Error: Personal Microsoft accounts (outlook.com, hotmail.com, live.com) have limited access to the To Do API through Microsoft Graph
- This is a Microsoft service limitation, not an issue with this application
- Work/school accounts have full API access

- Rate limits apply according to Microsoft's policies
- Some features may be unavailable for personal accounts
- Shared lists have limited functionality

- VerifyCLIENT_ID,CLIENT_SECRET, andTENANT_IDin your.envfile
- Ensure redirect URI matches exactly:http://localhost:3000/callback
- Check Azure App permissions are granted with admin consent

- Ensure all required Graph API permissions are added and consented
- For organizational accounts, admin consent may be required

TENANT_ID=organizations # Multi-tenant # Or use your specific tenant ID

TENANT_ID=consumers # Personal only # Or TENANT_ID=common for both types

# Using the MCP tool # In your AI assistant: "Check auth status" # Or examine tokens directly cat tokens.json | jq '.expiresAt' # Convert timestamp to readable date date -d @$(($(cat tokens.json | jq -r '.expiresAt') / 1000))

# The server logs to stderr for debugging mstodo 2> debug.log

- Fork the repository
- Create a feature branch
- Runpnpm run lintandpnpm run typecheckbefore submitting
- Submit a pull request

MIT License - SeeLICENSEfile for details

- Fork of@jhirono/todomcp
- Built on theModel Context Protocol SDK
- UsesMicrosoft Graph API

Official Taskeract MCP Server for integrating your Taskeract project tasks and load the context of your tasks into your MCP enabled app.