# Microsoft To Do MCP Server

[![M8ven Verified](https://m8ven.ai/badge/mcp/hoaaah-microsoft-to-do-mcp-server-1xsc5n?variant=verified)](https://m8ven.ai/mcp/hoaaah-microsoft-to-do-mcp-server-1xsc5n)

An [MCP](https://modelcontextprotocol.io) server that connects Claude (or any MCP-compatible client) to **Microsoft To Do** through the Microsoft Graph API — letting Claude read and manage your task lists and tasks on your behalf.

Runs entirely on your machine over stdio. No remote server ever sees your tasks or your tokens.

## Features

| Tool | Description |
|---|---|
| `todo_list_task_lists` | List all your task lists (Tasks, Groceries, etc.) |
| `todo_create_task_list` | Create a new task list |
| `todo_rename_task_list` | Rename an existing list |
| `todo_delete_task_list` | Delete a list and all its tasks (destructive) |
| `todo_list_tasks` | List tasks in a list, optionally filtered by status |
| `todo_get_task` | Get the details of a single task |
| `todo_create_task` | Create a task (title, notes, due date, importance) |
| `todo_update_task` | Update fields on an existing task |
| `todo_complete_task` | Mark a task as completed |
| `todo_delete_task` | Delete a task (destructive) |

## Prerequisites

- [Node.js](https://nodejs.org/) 18 or newer
- A Microsoft account (personal or work/school)
- [Claude Desktop](https://claude.ai/download) or another MCP-compatible client

## 1. Register an app in Azure AD

This server authenticates as your own Azure AD app registration, so you'll need to create one (free, takes a couple of minutes):

1. Go to the [Azure Portal → App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and click **New registration**.
2. Give it a name (e.g. "Microsoft To Do MCP"), and under **Supported account types** choose an option that includes personal Microsoft accounts, unless you only intend to use a work/school account.
3. Under **Redirect URI**, select platform **"Mobile and desktop applications"** and add:
   ```
   http://localhost:3000/callback
   ```
4. Click **Register**, then copy the **Application (client) ID** from the overview page — you'll need it later.
5. Go to **Authentication** and enable **"Allow public client flows"**, then save.
6. Go to **API permissions → Add a permission → Microsoft Graph → Delegated permissions**, and add:
   - `Tasks.ReadWrite`
   - `offline_access`
   - `User.Read`

## 2. Install & build

Clone this repository, then from the project folder:

```bash
git clone https://github.com/hoaaah/Microsoft-To-Do-MCP-Server.git
cd Microsoft-To-Do-MCP-Server
npm install
npm run build
```

This compiles the TypeScript source into `dist/index.js`.

## 3. Configure AI Client / Claude Desktop

Open your AI Client / Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the following entry, replacing `PATH_TO_THIS_FOLDER` with the absolute path to where you cloned this repo, and `MS_TODO_CLIENT_ID` with the Application (client) ID from Azure:

```json
{
  "mcpServers": {
    "microsoft-todo": {
      "command": "node",
      "args": ["PATH_TO_THIS_FOLDER/dist/index.js"],
      "env": {
        "MS_TODO_CLIENT_ID": "your-azure-client-id-here"
      }
    }
  }
}
```

Save the file and restart Claude Desktop.

## 4. First sign-in

The first time Claude calls one of the `todo_*` tools, your default browser will open automatically, asking you to sign in with your Microsoft account and approve the `Tasks.ReadWrite` permission. Once you approve, the token is cached locally at:

```
~/.microsoft-todo-mcp/token-cache.json
```

Subsequent sign-ins are silent — the cached refresh token is reused automatically as long as it hasn't expired or been revoked, so you won't need to log in again.

## Revoking access

To force a fresh sign-in, delete the cache file:

```
~/.microsoft-todo-mcp/token-cache.json
```

To fully revoke the app's access to your account, go to:
- [account.live.com/consent/Manage](https://account.live.com/consent/Manage) for personal Microsoft accounts
- **Azure AD → Enterprise Applications** for work/school accounts

## Security notes

- This server runs locally on your machine over stdio — there is no remote server storing or relaying your tokens.
- `todo_delete_task_list` and `todo_delete_task` are destructive and cannot be undone. Claude will ask for confirmation before calling them.
- Your Azure app's client ID is not a secret and is safe to keep in your local config, but you should not commit it to a public repository alongside real task data or tokens.

## Troubleshooting

- **Browser doesn't open on first sign-in**: make sure port `3000` is free, and that the redirect URI in your Azure app registration exactly matches `http://localhost:3000/callback`.
- **"Need admin approval" error**: your organization may require an admin to consent to the requested permissions — contact your Microsoft 365 administrator, or use a personal Microsoft account instead.
- **Claude doesn't see the tools**: double-check the path in `claude_desktop_config.json` points to the built `dist/index.js`, and that you restarted Claude Desktop after editing the config.

## License

[MIT](LICENSE)


# Creator

This MCP was created by and is maintained by **[Heru Arief Wijaya](http://belajararief.com/)**.

* https://twitter.com/hoaaah
* https://github.com/hoaaah