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 (Microsoft 365 business account recommended)
• Azure App Registration (see setup below)

2. Installation

Clone the repository and install dependencies:

git clone https://github.com/yourusername/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

Follow these steps to set up and use the MCP service:

1. Authenticate to get tokens

   npm run auth

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

2. Build the application

   npm run build

3. Create MCP config file (optional but recommended)

   npm run create-config

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

4. Run the application (choose one)

   # Using npm start
   npm run start
      
   # Using CLI directly
   npm run cli
      
   # Using npx with local package
   npx .

Running in Local Development

For development and testing:

# Build and run in one command
npm run dev

# Run CLI directly
node build/cli.js

Using with MCP Configuration

The recommended approach for tools like Claude or Cursor is to use an MCP configuration file:

1. First authenticate and create tokens:

   npm run auth

2. Generate the MCP configuration file:

   npm run create-config

3. Use the MCP file with Claude or Cursor (see below).

Using with Cursor

To use this MCP with Cursor, you need to configure it with your Microsoft Todo tokens. The configuration should be in .cursor/mcp.json:

{
  "mcpServers": {
    "mstodo": {
      "command": "npx",
      "args": ["-y", "@jhirono/todomcp"],
      "env": {
        "MSTODO_ACCESS_TOKEN": "your_access_token_here",
        "MSTODO_REFRESH_TOKEN": "your_refresh_token_here"
      }
    }
  }
}

You can generate this configuration automatically by running:

npm run auth        # First authenticate to get tokens
npm run create-config  # Then create the MCP configuration

Using with Claude

The Claude Desktop configuration should be similar. Add this to your Claude configuration file:

{
  "mcpServers": {
    "mstodo": {
      "command": "npx",
      "args": ["-y", "@jhirono/todomcp"],
      "env": {
        "MSTODO_ACCESS_TOKEN": "your_access_token_here",
        "MSTODO_REFRESH_TOKEN": "your_refresh_token_here"
      }
    }
  }
}

The 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

You can open it with the following commands:

macOS:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows (PowerShell):

notepad $env:APPDATA\Claude\claude_desktop_config.json

Linux:

xdg-open ~/.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

• Personal Microsoft accounts (outlook.com, hotmail.com, etc.) may experience the "MailboxNotEnabledForRESTAPI" error
• 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)