todoMCP

# 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 ```bash 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: ```bash git clone https://github.com/jhirono/todoMCP.git cd todoMCP npm install ``` ### 3. Azure App Registration 1. Go to the [Azure Portal](https://portal.azure.com) 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) ```bash 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) ```bash npm run create-config ``` This creates an `mcp.json` file with your authentication tokens. 3. **Set up the global MCP configuration** ```bash # 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: ```bash cat tokens.json | grep expiresAt ``` To convert the timestamp to a readable date: ```bash date -r $(echo "$(cat tokens.json | grep expiresAt | cut -d ":" -f2 | cut -d "," -f1) / 1000" | bc) ```