Skip to content
Back to search

microsoft-todo-mcp-server

A Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor to interact with Microsoft To Do via the Microsoft Graph API. This service provides comprehensive task…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jordanburke/microsoft-todo-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jordanburke/microsoft-todo-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jordanburke--microsoft-todo-mcp-server/badge.svg)](/listings/jordanburke--microsoft-todo-mcp-server)

HTML

<a href="/listings/jordanburke--microsoft-todo-mcp-server"><img src="/api/listings/jordanburke--microsoft-todo-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: Global Installation (Recommended)

# Install globally using npm
npm install -g microsoft-todo-mcp-server

# Or using pnpm
pnpm install -g microsoft-todo-mcp-server

# Or run directly with npx (no installation)
npx microsoft-todo-mcp-server

The package provides three command aliases:

- `microsoft-todo-mcp-server` - Full package name - `mstodo` - Short alias for the MCP server - `mstodo-config` - Configuration helper tool

Option 2: Clone and Run Locally

git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
pnpm install
pnpm run build

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 474 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Microsoft To Do MCP
  2. [![CI](https://github.com/jordanburke/microsoft-todo-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/jordanburke/microsoft-todo-mcp-server/actions/workflows/ci.yml)
  3. [![npm version](https://badge.fury.io/js/microsoft-todo-mcp-server.svg)](https://www.npmjs.com/package/microsoft-todo-mcp-server)
  4. A Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor to interact with Microsoft To Do via the Microsoft Graph API. This service provides comprehensive task management capabilities through a secure OAuth 2.0 authentication flow.
  5. ## Just want to try it? Use Agent Todo
  6. Running this server yourself means registering an app in Azure and managing its client secret. If you'd rather skip that, [Agent Todo](https://agent-todo.com) is a hosted MCP server that supports Microsoft To Do, from the same maintainer. You sign in to Agent Todo, connect your Microsoft To Do account on its Connections page, then add the connector to your AI assistant. There's nothing to register or install.
  7. - **Free plan:** one connected task provider, such as Microsoft To Do, with read and write access.
  8. - **Pro plan:** every provider (Google Tasks and Todoist too), with sync between them.
  9. Connect it from any MCP client that supports remote servers. It signs you in with OAuth on first use.
  10. ```bash
  11. # Claude Code
  12. claude mcp add --transport http agent-todo https://api.agent-gate.com/agent-todo/mcp
  13. ```
  14. In Claude Desktop or claude.ai, open Settings, then Connectors, and add `https://api.agent-gate.com/agent-todo/mcp` as a custom connector.
  15. Want to run it on your own machine, or keep your tokens local? Keep reading to set up this server.
  16. ## Features
  17. - **17 MCP Tools**: Complete task management functionality including lists, tasks, checklist items, and organization features
  18. - **Recurring Tasks**: First-class support for Microsoft Graph `recurrence` (daily / weekly / absoluteMonthly / relativeMonthly / absoluteYearly / relativeYearly) on `create-task` and `update-task`
  19. - **OAuth 2.0 Authentication**: Sign in once; tokens renew automatically
  20. - **Microsoft Graph API Integration**: Direct integration with Microsoft's official API
  21. - **Multi-tenant Support**: Works with personal, work, and school Microsoft accounts
  22. - **Built on [somamcp](https://www.npmjs.com/package/somamcp)**: MCP SDK 2.x underneath, served over stdio
  23. - **TypeScript**: Fully typed for reliability and developer experience
  24. - **ESM Modules**: Modern JavaScript module system
  25. ## Prerequisites
  26. - Node.js 22.18 or higher (CI tests 22.18.0, 24.x and 26.x); building from source needs 22.18+, 24.11+ or 26+
  27. - pnpm, only to build from source
  28. - A Microsoft account (personal, work, or school)
  29. - Azure App Registration (see setup below)
  30. ## Installation
  31. ### Option 1: Global Installation (Recommended)
  32. ```bash
  33. # Install globally using npm
  34. npm install -g microsoft-todo-mcp-server
  35. # Or using pnpm
  36. pnpm install -g microsoft-todo-mcp-server
  37. # Or run directly with npx (no installation)
  38. npx microsoft-todo-mcp-server
  39. ```
  40. The package provides five commands:
  41. - `microsoft-todo-mcp-server` - The MCP server
  42. - `mstodo` - Short alias for the MCP server
  43. - `mstodo-config` - Writes an `mcp.json` that points the server at your `tokens.json`
  44. - `mstodo-setup` - Guided setup. It does not yet finish on its own after you sign in, so use the steps under [Usage](#usage) instead
  45. - `mstodo-http` - The MCP server over HTTP, for remote clients; each user signs in with their own Microsoft account (see [HTTP Mode](#http-mode-remote-clients))
  46. ### Option 2: Clone and Run Locally
  47. ```bash
  48. git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
  49. cd microsoft-todo-mcp-server
  50. pnpm install
  51. pnpm run build
  52. ```
  53. ## Azure App Registration
  54. 1. Go to the [Azure Portal](https://portal.azure.com)
  55. 2. Navigate to "App registrations" and create a new registration
  56. 3. Name your application (e.g., "To Do MCP")
  57. 4. For "Supported account types", select one of the following based on your needs:
  58. - **Accounts in this organizational directory only (Single tenant)** - For use within a single organization
  59. - **Accounts in any organizational directory (Any Azure AD directory - Multitenant)** - For use across multiple organizations
  60. - **Accounts in any organizational directory and personal Microsoft accounts** - For both work accounts and personal accounts
  61. 5. Add a **Web** platform redirect URI: `http://localhost:3000/callback`. For [HTTP Mode](#http-mode-remote-clients), also add `<your base URL>/oauth/callback`
  62. 6. After creating the app, go to "Certificates & secrets" and create a new client secret. Note when it expires: sign-in and token renewal stop working on that date
  63. 7. Go to "API permissions" and add these Microsoft Graph delegated permissions. The sign-in requests these (plus the standard `openid` and `profile`), so adding them here is what lets an admin approve them ahead of time:
  64. - `Tasks.Read`, `Tasks.ReadWrite`, `Tasks.Read.Shared`, `Tasks.ReadWrite.Shared`
  65. - `User.Read`, `offline_access`
  66. 8. For a work or school tenant that requires it, an admin clicks "Grant admin consent". Personal accounts consent on the sign-in page
  67. ## Configuration
  68. ### Environment Setup
  69. Create a `.env` file in the repository root, where you run `pnpm run auth` (required for sign-in):
  70. ```env
  71. CLIENT_ID=your_client_id
  72. CLIENT_SECRET=your_client_secret
  73. TENANT_ID=your_tenant_setting
  74. REDIRECT_URI=http://localhost:3000/callback
  75. ```
  76. ### TENANT_ID Options
  77. - `organizations` - For multi-tenant organizational accounts (the default when `TENANT_ID` is unset)
  78. - `consumers` - For personal Microsoft accounts only
  79. - `common` - For both organizational and personal accounts
  80. - `your-specific-tenant-id` - For single-tenant configurations
  81. **Examples:**
  82. ```env
  83. # For multi-tenant organizational accounts (default)
  84. TENANT_ID=organizations
  85. # For personal Microsoft accounts
  86. TENANT_ID=consumers
  87. # For both organizational and personal accounts
  88. TENANT_ID=common
  89. # For a specific organization tenant
  90. TENANT_ID=00000000-0000-0000-0000-000000000000
  91. ```
  92. ### Token Storage
  93. The server stores authentication tokens in `tokens.json`. It looks in three places, in order:
  94. 1. `MSTODO_TOKEN_FILE`, if set
  95. 2. the per-user config directory — `~/.config/microsoft-todo-mcp/tokens.json`, or `%APPDATA%\microsoft-todo-mcp\tokens.json` on Windows
  96. 3. `tokens.json` in the working directory, which is migrated to whichever of (1) or (2) is in effect on first read
  97. ```bash
  98. # Override the location
  99. export MSTODO_TOKEN_FILE=/path/to/custom/tokens.json
  100. ```
  101. You can also supply tokens directly, which takes precedence over the file:
  102. ```bash
  103. export MS_TODO_ACCESS_TOKEN=your_access_token
  104. export MS_TODO_REFRESH_TOKEN=your_refresh_token
  105. ```
  106. These two are a starting point, not a live store — nothing rewrites your environment when a token is renewed. A renewal is kept for the rest of the session and written to the token file. On later launches the server uses that token file instead, as long as the environment still holds the same pair it was renewed from; set a new pair, for example after signing in again, and it starts over from that.
  107. How the expiry is known depends on your account type. Work and school accounts get a JWT access token, so the server reads the real deadline from it and renews 5 minutes early. Personal accounts get an opaque token, where there is nothing to read and the server assumes an hour from when it first saw the value. Either way renewal needs `CLIENT_ID` and `CLIENT_SECRET`; without them the server cannot refresh, and calls start failing once the supplied token runs out.
  108. ## Usage
  109. ### Complete Setup Workflow
  110. #### Step 1: Sign in with Microsoft
  111. Sign-in runs from a clone of this repository, with the `.env` file from [Configuration](#configuration) in its root:
  112. ```bash
  113. git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
  114. cd microsoft-todo-mcp-server
  115. pnpm install
  116. pnpm run build
  117. pnpm run auth
  118. ```
  119. Open <http://localhost:3000> and sign in. Microsoft sends you back to `/callback`, and the server writes `tokens.json` in the repository root. Stop it with Ctrl+C when the page says authentication succeeded.
  120. #### Step 2: Move the tokens where the server looks
  121. `tokens.json` holds your refresh token and your client secret, so keep it private:
  122. ```bash
  123. # macOS and Linux
  124. mkdir -p ~/.config/microsoft-todo-mcp
  125. mv tokens.json ~/.config/microsoft-todo-mcp/tokens.json
  126. chmod 600 ~/.config/microsoft-todo-mcp/tokens.json
  127. ```
  128. On Windows, move it to `%APPDATA%\microsoft-todo-mcp\tokens.json`. To keep it elsewhere, set `MSTODO_TOKEN_FILE` to its path in the next step.
  129. #### Step 3: Configure Your AI Assistant
  130. The server finds the token file itself and renews tokens with the client credentials stored in it, so the config needs no secrets.
  131. **Claude Code:**
  132. ```bash
  133. claude mcp add -s user microsoft-todo -- npx -y microsoft-todo-mcp-server
  134. # Token file somewhere else:
  135. claude mcp add -s user microsoft-todo -e MSTODO_TOKEN_FILE=/path/to/tokens.json -- npx -y microsoft-todo-mcp-server
  136. ```
  137. `-s user` makes it available in every project; without it, Claude Code adds it only to the folder you ran the command in.
  138. **Claude Desktop:** add this to its config file:
  139. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  140. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  141. - **Linux**: `~/.config/Claude/claude_desktop_config.json`
  142. ```json
  143. {
  144. "mcpServers": {
  145. "microsoftTodo": {
  146. "command": "npx",
  147. "args": ["--yes", "microsoft-todo-mcp-server"]
  148. }
  149. }
  150. }
  151. ```
  152. Add `"env": { "MSTODO_TOKEN_FILE": "/path/to/tokens.json" }` if the file is not in the default location.
  153. **Cursor:** add the same `mcpServers` entry to `~/.cursor/mcp.json`.
  154. **About `mstodo-config`:** `pnpm run create-config` (or `mstodo-config`) writes an `mcp.json` with the entry above, plus `MSTODO_TOKEN_FILE` set to the token file's absolute path. It copies no tokens into the config. It warns if the token file lacks `clientId` and `clientSecret`, which renewal needs.
  155. **About token environment variables:** if you pass `MS_TODO_ACCESS_TOKEN` and `MS_TODO_REFRESH_TOKEN` instead, renewing them also needs `CLIENT_ID` and `CLIENT_SECRET` in the same `env` block, plus `TENANT_ID` unless it is `organizations`. Without them, calls start failing when the access token expires, within about an hour of signing in. The token-file setup above avoids this.
  156. **Upgrading from an older version:** older versions copied renewed tokens into Claude Desktop's config as `MS_TODO_ACCESS_TOKEN` and `MS_TODO_REFRESH_TOKEN`, and older `mstodo-config` wrote them into `mcp.json`. The server now picks up its token file when that file holds the same refresh token, which heals the copied Claude Desktop entries. An old `mcp.json` sets no `MSTODO_TOKEN_FILE`, so it heals only if the server's token file (the default location, or `MSTODO_TOKEN_FILE`) is the one that pair came from. Either way, the fix that always works is to delete those two variables from the entry, so the server reads only the token file. Do the same if you sign in again: a fresh token file is ignored while an old pair is still set.
  157. ### Available Scripts
  158. ```bash
  159. # Development & Building
  160. pnpm run build # Build TypeScript to JavaScript
  161. pnpm run dev # Build and run CLI in one command
  162. pnpm run validate # Format, lint, typecheck, test and build (fixes format and lint)
  163. pnpm run ci # The same checks without fixing anything; what CI runs
  164. pnpm test # Run the tests
  165. # Running the Server
  166. pnpm start # Run MCP server (dist/cli.js)
  167. pnpm run cli # Run MCP server via CLI wrapper
  168. npx microsoft-todo-mcp-server # Run globally installed version
  169. # Authentication & Configuration
  170. pnpm run auth # Start OAuth authentication server
  171. pnpm run create-config # Generate mcp.json from tokens.json
  172. # Code Quality
  173. pnpm run format # Format code with Prettier
  174. pnpm run format:check # Check code formatting
  175. pnpm run lint # Run linting checks
  176. pnpm run typecheck # TypeScript type checking
  177. ```
  178. ## HTTP Mode (remote clients)
  179. `mstodo-http` serves the same tools over Streamable HTTP, for clients that connect by URL, such as a Claude custom connector. It is its own OAuth server in front of Microsoft, built on somamcp's Azure provider:
  180. - **Each user signs in with their own Microsoft account**, and each tool call uses that user's token. The host's `tokens.json` and `MS_TODO_*` variables are never read in this mode.
  181. - **The client never sees a Microsoft token.** It gets the server's own tokens; Microsoft's stay in an encrypted store on the server, which renews them when the client refreshes.
  182. - **Stateless:** each request is served on its own, and sign-ins live in the store, not in memory. Several instances can sit behind a load balancer if they share the store directory and both keys.
  183. ### Setup
  184. 1. **On the app registration** (see [Azure App Registration](#azure-app-registration)), add a **Web** redirect URI: `<your base URL>/oauth/callback`, for example `https://todo.example.com/oauth/callback`.
  185. 2. **Set these**, in the environment or a `.env` in the working directory:
  186. | Variable | Required | Meaning |
  187. | ----------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  188. | `MSTODO_HTTP_BASE_URL` | yes | The server's public origin, such as `https://todo.example.com`: `https` (plain `http` only for `localhost`), with no path. A reverse proxy that mounts the server under a path must strip it. |
  189. | `CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID` | yes | The app registration. Use the tenant's id (a GUID) for a work or school tenant: sign-ins from other tenants are then refused. Use `consumers` for personal accounts only; `common` on a multi-tenant app also admits every work or school tenant. |
  190. | `JWT_SIGNING_KEY`, `TOKEN_ENCRYPTION_KEY` | yes | Two different keys of at least 32 characters, such as `openssl rand -base64 48`. Keep them: changing either signs everyone out. |
  191. | `MSTODO_HTTP_ALLOWED_USERS` | recommended | Comma-separated accounts allowed to sign in, by object id, sign-in name or email. With `common` or `organizations`, list object ids: another tenant can issue an id token with any email in it. Without the setting, any account the app registration accepts can sign in, and each sees only its own To Do. |
  192. | `MSTODO_HTTP_PORT`, `MSTODO_HTTP_HOST` | no | Where to listen. Defaults: `3100` on `127.0.0.1`. Use `0.0.0.0` in a container. |
  193. | `MSTODO_HTTP_STORE` | no | Where sign-ins are stored, encrypted. Default `~/.config/microsoft-todo-mcp/http-store`. It must be writable; the server checks at startup. |
  194. | `MSTODO_HTTP_REDIRECT_URIS` | no | Comma-separated redirect URI patterns a client may register. Default: `https://claude.ai/*`, `http://localhost:*/*`, `http://127.0.0.1:*/*`. Each pattern must spell out its scheme and host in lower case; `*` and `?` match only in the path, so `https://claude.ai*` is refused. Only `localhost` may use `http` or leave the port open. |
  195. 3. **Run it** behind HTTPS (a reverse proxy such as Caddy or nginx, or a tunnel):
  196. ```bash
  197. mstodo-http # or: npx -p microsoft-todo-mcp-server mstodo-http
  198. ```
  199. It refuses to start, and lists what is wrong, until every required setting is valid.
  200. 4. **Connect a client** to `<your base URL>/mcp`. The client discovers the OAuth endpoints, registers itself, and sends you to Microsoft to sign in. Finish signing in within a day: a client nobody signs in with lapses after 24 hours, and then has to be removed and added again. A client that has signed in lasts 90 days after its last sign-in or refresh.
  201. `auth-status` reports who is signed in and when their Microsoft token expires.
  202. ## MCP Tools
  203. The server provides 17 tools for comprehensive Microsoft To Do management:
  204. ### Authentication and Server Info
  205. - **`auth-status`** - Check authentication status, token expiration, and account type
  206. - **`info`** - Report the server's name, version, build, runtime, and tool count (from [somamcp](https://www.npmjs.com/package/somamcp); build details come from the `SOMAMCP_BUILD_COMMIT`, `SOMAMCP_BUILD_DATE`, `SOMAMCP_BUILD_BRANCH` and `SOMAMCP_ENVIRONMENT` environment variables when set)
  207. ### Task Lists (Top-level Containers)
  208. - **`get-task-lists`** - Retrieve all task lists with metadata (default, shared, etc.)
  209. - **`create-task-list`** - Create a new task list
  210. - **`update-task-list`** - Rename an existing task list
  211. - **`delete-task-list`** - Delete a task list and all its contents
  212. - **`get-task-lists-organized`** - Group task lists into folders by naming pattern, emoji prefix, or sharing status (`groupBy`: `category`, `shared`, or `type`; `includeIds` adds an ID reference)
  213. ### Tasks (Main Todo Items)
  214. - **`get-tasks`** - Get tasks from a list with filtering, sorting, and pagination
  215. - Supports OData query parameters: `$filter`, `$orderby`, `$top`, `$skip`, `$count`
  216. - `orderby` works on date fields such as `createdDateTime`; Graph rejects `orderby=title`
  217. - `top` caps the total, and the server follows Graph's paging to collect every page
  218. - `count` prints the number of tasks returned; Graph itself returns no count for To Do tasks
  219. - `select` limits which fields print (`status`, `dueDateTime`, `importance`, `categories`, `recurrence`, `body`); it is applied by the server, not sent to Graph
  220. - **`create-task`** - Create a new task with full property support
  221. - Title, description, due date, start date, importance, reminders, status, categories, **recurrence**
  222. - **`update-task`** - Update any task properties including **recurrence** (pass `null` to stop a recurring task)
  223. - **`delete-task`** - Delete a task and all its checklist items
  224. ### Recurring Tasks
  225. Pass a `recurrence` object to `create-task` or `update-task` to make a task repeat.
  226. Recurrence derives its first occurrence from the task's `dueDateTime`, which is
  227. required. Examples:
  228. ```json
  229. // Monthly bill, 15th of every month, forever
  230. {
  231. "pattern": {"type": "absoluteMonthly", "interval": 1, "dayOfMonth": 15},
  232. "range": {"type": "noEnd"}
  233. }
  234. // Weekly standup every Monday, ends 2027-01-01
  235. {
  236. "pattern": {"type": "weekly", "interval": 1, "daysOfWeek": ["monday"]},
  237. "range": {"type": "endDate", "endDate": "2027-01-01"}
  238. }
  239. // Annual birthday, on the 4th of September
  240. {
  241. "pattern": {"type": "absoluteYearly", "interval": 1, "dayOfMonth": 4, "month": 9},
  242. "range": {"type": "noEnd"}
  243. }
  244. ```
  245. Each pattern type needs its own fields, and the server refuses a rule that leaves one
  246. out or adds one the type does not use: `weekly` and `relativeMonthly` take `daysOfWeek`,
  247. `absoluteMonthly` takes `dayOfMonth`, `absoluteYearly` takes `dayOfMonth` and `month`,
  248. and `relativeYearly` takes `daysOfWeek` and `month`. A `weekly` rule without
  249. `firstDayOfWeek` gets `sunday`. An `endDate` range needs `endDate`, and a `numbered`
  250. range needs `numberOfOccurrences`.
  251. Stop a recurring task by passing `recurrence: null` to `update-task`. See
  252. <https://learn.microsoft.com/en-us/graph/api/resources/recurrencepattern> for
  253. the full schema.
  254. ### Checklist Items (Subtasks)
  255. - **`get-checklist-items`** - Get subtasks for a specific task
  256. - **`create-checklist-item`** - Add a new subtask to a task
  257. - **`update-checklist-item`** - Update subtask text or completion status
  258. - **`delete-checklist-item`** - Remove a specific subtask
  259. ### Maintenance and Diagnostics
  260. - **`archive-completed-tasks`** - Move completed tasks older than `olderThanDays` (default 90) from one list to another; `dryRun` previews without moving
  261. - **`test-graph-api-exploration`** - Run read-only Graph API probes (`odata-select`, `odata-expand`, `headers`, `extensions`, or `all`) to look for hidden list properties; for debugging, not everyday use
  262. ## Architecture
  263. ### Project Structure
  264. - **MCP Server** (`src/todo-index.ts`) - The 16 To Do tools, registered on a somamcp server
  265. - **Token Manager** (`src/token-manager.ts`) - Finds, renews and saves tokens
  266. - **CLI Wrapper** (`src/cli.ts`) - Executable entry point; starts the server over stdio
  267. - **Auth Server** (`src/auth-server.ts`) - Express server for the OAuth 2.0 sign-in
  268. - **Setup** (`src/setup.ts`) - The guided `mstodo-setup` command
  269. - **Config Generator** (`src/create-mcp-config.ts`) - Helper to create MCP configurations
  270. ### Technical Details
  271. - **MCP framework**: [somamcp](https://www.npmjs.com/package/somamcp) 2.x, with Zod 4 parameter schemas
  272. - **Microsoft Graph API**: Uses v1.0 endpoints
  273. - **Authentication**: MSAL (Microsoft Authentication Library) authorization-code flow with a client secret
  274. - **Token Management**: Renews 5 minutes before expiry, and again whenever Graph rejects a token
  275. - **Build System**: ts-builds (tsdown) for fast TypeScript compilation
  276. - **Module System**: ESM (ECMAScript modules)
  277. ## Limitations & Known Issues
  278. ### Personal Microsoft Accounts
  279. - Personal accounts (outlook.com, hotmail.com, live.com) work. A live.com account tested on 2026-10-31 had full access: 30 lists, paging through a 399-task list, writes and recurring tasks
  280. - If you see `MailboxNotEnabledForRESTAPI`, Microsoft has not enabled the To Do API for that mailbox. It is a Microsoft-side limit, not a bug in this server, and the server says so when it happens
  281. ### API Limitations
  282. - Rate limits apply according to Microsoft's policies
  283. - Shared lists have limited functionality
  284. ## Troubleshooting
  285. ### Authentication Issues
  286. **Token acquisition failures**
  287. - `unauthorized_client: The client does not exist or is not enabled for consumers`: Microsoft can't use the app for this account. Either the app registration was deleted, or its supported account types exclude personal accounts
  288. - `AADSTS7000215` (invalid client secret) or `AADSTS7000222` (expired client secret): create a new secret under "Certificates & secrets" and update `.env`, then sign in again so `tokens.json` stores it
  289. - Verify `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID` in your `.env` file
  290. - Ensure redirect URI matches exactly: `http://localhost:3000/callback`
  291. - Check Azure App permissions are granted with admin consent
  292. **Permission issues**
  293. - Ensure all required Graph API permissions are added and consented
  294. - For organizational accounts, admin consent may be required
  295. ### Account Type Configuration
  296. **Work/School Accounts**
  297. ```env
  298. TENANT_ID=organizations # Multi-tenant
  299. # Or use your specific tenant ID
  300. ```
  301. **Personal Accounts**
  302. ```env
  303. TENANT_ID=consumers # Personal only
  304. # Or TENANT_ID=common for both types
  305. ```
  306. ### Debugging
  307. **Check authentication status:**
  308. ```bash
  309. # Using the MCP tool
  310. # In your AI assistant: "Check auth status"
  311. # Or read the expiry from the token file (it also holds secrets, so don't share its contents)
  312. jq '.expiresAt' ~/.config/microsoft-todo-mcp/tokens.json
  313. # Convert the timestamp to a readable date
  314. date -d @$(($(jq -r '.expiresAt' ~/.config/microsoft-todo-mcp/tokens.json) / 1000))
  315. ```
  316. **Enable verbose logging:**
  317. ```bash
  318. # The server logs to stderr for debugging
  319. mstodo 2> debug.log
  320. ```
  321. ## Contributing
  322. Contributions are welcome! Please:
  323. 1. Fork the repository
  324. 2. Create a feature branch
  325. 3. Run `pnpm run validate` (format, lint, typecheck, test, build) before submitting; CI runs `pnpm run ci`, the same checks without fixing
  326. 4. Submit a pull request
  327. ## License
  328. MIT License - See [LICENSE](LICENSE) file for details
  329. ## Acknowledgments
  330. - Fork of [@jhirono/todomcp](https://github.com/jhirono/todomcp)
  331. - Built on [somamcp](https://www.npmjs.com/package/somamcp) and the [Model Context Protocol](https://modelcontextprotocol.io) TypeScript SDK
  332. - Uses [Microsoft Graph API](https://developer.microsoft.com/en-us/graph)
  333. ## Support
  334. - [GitHub Issues](https://github.com/jordanburke/microsoft-todo-mcp-server/issues)
  335. - [npm Package](https://www.npmjs.com/package/microsoft-todo-mcp-server)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.