Microsoft Todo MCP server for AI agents

Microsoft To Do MCP provides an interface that lets you manage your Microsoft To Do tasks through an AI assistant, allowing seamless task management directly through conversational commands.

Prerequisites

Node.js 16 or higher
npm
A Microsoft account
Azure App Registration

Installation

The installation process involves two main steps: installing the package and setting up authentication.

Installing the Package

npm install -g @jhirono/todomcp

Setting Up Authentication

Even with a global package installation, you need to clone the repository to complete authentication:

git clone https://github.com/jhirono/todoMCP.git
cd todoMCP
npm install

Azure Configuration

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:
- Accounts in this organizational directory only (Single tenant)
- Accounts in any organizational directory (Any Azure AD directory - Multitenant)
- Accounts in any organizational directory and personal Microsoft accounts
Set the Redirect URI to http://localhost:3000/callback
After creating the app, create a new client secret under "Certificates & secrets"
Add the following permissions under "API permissions":
- Microsoft Graph > Delegated permissions:
  - Tasks.Read
  - Tasks.ReadWrite
  - User.Read
Click "Grant admin consent" for these permissions

Environment Configuration

Create a .env file in the root directory with your configuration:

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
consumers - For personal Microsoft accounts only
common - For both organizational and personal accounts
your-specific-tenant-id - For single-tenant configurations

Using the MCP Service

Authentication Process

Run the authentication command from the cloned repository:
```
npm run auth
```
This opens a browser window for Microsoft authentication and creates a tokens.json file.
Create the MCP configuration file:
```
npm run create-config
```
This generates an mcp.json file containing your authentication tokens.

Set up global MCP configuration:

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

AI Assistant Integration

After configuration, you can use Microsoft To Do commands directly in Cursor. Try commands like:

auth status
list up todos

For Claude Desktop, 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

Available Tools

The MCP service provides several tools for task management:

Authentication

auth-status: Check your authentication status

Task Lists Management

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

Tasks Management

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

Checklist Items

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

Troubleshooting

Authentication Issues

"MailboxNotEnabledForRESTAPI" error: Typically occurs with personal Microsoft accounts due to limited Graph API access.
Token acquisition failures: Verify your CLIENT_ID, CLIENT_SECRET, and TENANT_ID in the .env file.
Permission issues: Ensure you've granted admin consent for the required permissions.

Account Type Considerations

Work/School Accounts: Work best with the To Do API. Use TENANT_ID=organizations or your specific tenant ID.
Personal Accounts: Have limited API access. Try using TENANT_ID=consumers or TENANT_ID=common.

Verifying Authentication Status

Check your authentication status with the auth-status tool or examine token expiration:

cat tokens.json | grep expiresAt

Convert the timestamp to a readable date:

date -r $(echo "$(cat tokens.json | grep expiresAt | cut -d ":" -f2 | cut -d "," -f1) / 1000" | bc)

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.