Microsoft To Do MCP
This MCP (Model Context Protocol) service allows you to interact with Microsoft To Do tasks using an AI assistant.
Setup Instructions
1. Prerequisites
- Node.js 16 or higher
- npm
- A Microsoft account
- Azure App Registration (see setup below)
2. Installation
There are two parts to installing this tool:
- Installing the package
- Setting up authentication (requires cloning the repository)
Step 1: Install the Package
npm install -g @jhirono/todomcp
Step 2: Set Up Authentication
Even if you install the package globally, you'll need to clone the repository to complete the authentication process:
git clone https://github.com/jhirono/todoMCP.git
cd todoMCP
npm install
3. Azure App Registration
- Go to the Azure 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:
- 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
- Set the Redirect URI to
http://localhost:3000/callback - After creating the app, go to "Certificates & secrets" and create a new client secret
- Go to "API permissions" and add the following permissions:
- Microsoft Graph > Delegated permissions:
- Tasks.Read
- Tasks.ReadWrite
- User.Read
- Microsoft Graph > Delegated permissions:
- Click "Grant admin consent" for these permissions
4. Configuration
Create a .env file in the root directory with the following information:
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 (default if not specified)consumers- For personal Microsoft accounts onlycommon- For both organizational and personal accountsyour-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
Usage
Complete Workflow
-
Authenticate to get tokens (must be done from the cloned repository)
npm run authThis will open a browser window for you to authenticate with Microsoft and create a
tokens.jsonfile. -
Create MCP config file (must be done from the cloned repository)
npm run create-configThis creates an
mcp.jsonfile with your authentication tokens. -
Set up the global MCP configuration
# Copy the mcp.json file to your global Cursor configuration directory cp mcp.json ~/.cursor/mcp-servers.jsonThis makes the Microsoft To Do MCP available across all your Cursor projects.
-
Start using with your AI assistant
- In Cursor, you can now use Microsoft To Do commands directly in any project
- Try commands like
auth statusorlist up todosto get started
The Claude Desktop configuration file is located at:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Available Tools
auth-status: Check your authentication statusget-task-lists: Get all your To Do task listscreate-task-list: Create a new task listupdate-task-list: Update an existing task listdelete-task-list: Delete a task listget-tasks: Get all tasks in a listcreate-task: Create a new taskupdate-task: Update an existing taskdelete-task: Delete a taskget-checklist-items: Get checklist items for a taskcreate-checklist-item: Create a checklist itemupdate-checklist-item: Update a checklist itemdelete-checklist-item: Delete a checklist item
Limitations
- The API requires proper authentication and permissions
- Rate limits may apply according to Microsoft's policies
Troubleshooting
Authentication Issues
-
"MailboxNotEnabledForRESTAPI" error: This typically means you're using a personal Microsoft account. Microsoft To Do API access is limited for personal accounts through the Graph API.
-
Token acquisition failures: Make sure your
CLIENT_ID,CLIENT_SECRET, andTENANT_IDare correct in your.envfile. -
Permission issues: Ensure you have granted admin consent for the required permissions in your Azure App registration.
Account Type Issues
-
Work/School Accounts: These typically work best with the To Do API. Use
TENANT_ID=organizationsor your specific tenant ID. -
Personal Accounts: These have limited access to the To Do API. If you must use a personal account, try
TENANT_ID=consumersorTENANT_ID=common.
Checking Authentication Status
You can check your authentication status using the auth-status tool or by examining the expiration time in your tokens:
cat tokens.json | grep expiresAt
To convert the timestamp to a readable date:
date -r $(echo "$(cat tokens.json | grep expiresAt | cut -d ":" -f2 | cut -d "," -f1) / 1000" | bc)