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:

1. Installing the package
2. 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

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
5. Set the Redirect URI to http://localhost:3000/callback
6. After creating the app, go to "Certificates & secrets" and create a new client secret
7. Go to "API permissions" and add the following permissions:
   • Microsoft Graph > Delegated permissions:
     • Tasks.Read
     • Tasks.ReadWrite
     • User.Read
8. 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 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

Usage

Complete Workflow

1. Authenticate to get tokens (must be done from the cloned repository)

   npm run auth

   This will open a browser window for you to authenticate with Microsoft and create a tokens.json file.

2. Create MCP config file (must be done from the cloned repository)

   npm run create-config

   This creates an mcp.json file with your authentication tokens.

3. Set up the global MCP configuration

   # Copy the mcp.json file to your global Cursor configuration directory
   cp mcp.json ~/.cursor/mcp-servers.json

   This makes the Microsoft To Do MCP available across all your Cursor projects.

4. Start using with your AI assistant

   • In Cursor, you can now use Microsoft To Do commands directly in any project
   • Try commands like auth status or list up todos to 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 status
• get-task-lists: Get all your To Do task lists
• create-task-list: Create a new task list
• update-task-list: Update an existing task list
• delete-task-list: Delete a task list
• get-tasks: Get all tasks in a list
• create-task: Create a new task
• update-task: Update an existing task
• delete-task: Delete a task
• get-checklist-items: Get checklist items for a task
• create-checklist-item: Create a checklist item
• update-checklist-item: Update a checklist item
• delete-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, and TENANT_ID are correct in your .env file.

• 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=organizations or 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=consumers or TENANT_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)