Microsoft To Do MCP — Self Hosted

A self-hosted Model Context Protocol server for Microsoft To Do. The key problem this solves: the Microsoft Graph API silently omits user-created lists on personal accounts (GET /me/todo/lists only returns well-known lists like "Flagged Emails"). This server works around it with a local SQLite registry that tracks every list you create, so your lists always show up.

Run it on your own VPS, expose it over HTTPS, and connect any MCP-compatible AI client (Claude Code, Cursor, Claude Desktop) from any machine.

Credits: Based on jordanburke/microsoft-todo-mcp-server, which is a fork of @jhirono/todomcp.

The problem this fixes

Microsoft's Graph API has a limitation for personal Microsoft accounts (outlook.com, hotmail.com, live.com, Gmail linked accounts, etc.):

• POST /me/todo/lists — works, creates the list, returns an ID ✅

• GET /me/todo/lists — only returns built-in lists like "Flagged Emails", silently drops everything you created ❌

This means any MCP server that relies purely on the API for listing will never show your custom lists. This repo fixes it by maintaining a local SQLite database (lists.db) that persists every list created through the server, then merges it with the API response so nothing is ever missing.

Related MCP server: MCP for Microsoft To Do

How it works

Your laptop / any machine
        │
        │  claude mcp add --transport http ...
        ▼
https://todo-mcp.yourdomain.com
        │
        ├── /          → Dashboard (connection status + quick-add commands)
        ├── /auth      → Start Microsoft OAuth
        ├── /callback  → OAuth callback (saves tokens)
        ├── /health    → Health check
        └── /mcp       → MCP endpoint (API key protected)

You authenticate once via the dashboard. Tokens are stored on your server and auto-refreshed. Your API key protects the MCP endpoint so only your machines can use it.

Features

• Fixes personal account list limitation — a local list registry ensures all your lists are always visible

• SQLite or Postgres — zero-config SQLite file by default, or point DATABASE_URL at Postgres

• HTTP transport — connect from any machine, not just localhost

• Dashboard — web UI to connect your Microsoft account and get copy-paste setup commands for Claude Code, Cursor, and Claude Desktop

• API key auth — protects the /mcp endpoint

• Dashboard password — HTTP basic auth on the dashboard so only you can access it

• Auto token refresh — tokens refresh automatically, no manual intervention

• 15 MCP tools — full task management: lists, tasks, checklist items

Prerequisites

• Node.js 18+

• A server or VPS (DigitalOcean, Hetzner, etc.) with a domain pointed at it

• A Microsoft account (personal or work)

• An Azure App Registration (see below)

Azure App Registration

1. Go to portal.azure.com → App registrations → New registration

2. Name it (e.g. todo-mcp)

3. Supported account types: Personal Microsoft accounts (consumers) or any account (common)

4. Redirect URI: https://todo-mcp.yourdomain.com/callback (Web)

5. After creating, go to Certificates & secrets → create a client secret, copy it

6. Go to API permissions → Add → Microsoft Graph → Delegated:

   • Tasks.Read, Tasks.ReadWrite, Tasks.Read.Shared, Tasks.ReadWrite.Shared, User.Read

7. Click Grant admin consent

8. Copy your Application (client) ID from the Overview page

Setup

1. Clone and install

git clone https://github.com/akkilesh-a/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
npm install
npm run build

2. Configure environment

cp .env.example .env

Edit .env:

CLIENT_ID=your_azure_app_client_id
CLIENT_SECRET=your_azure_app_client_secret
TENANT_ID=consumers
PORT=3001
PUBLIC_URL=https://todo-mcp.yourdomain.com
REDIRECT_URI=https://todo-mcp.yourdomain.com/callback
MCP_API_KEY=your_secret_api_key        # openssl rand -hex 32
DASHBOARD_USERNAME=admin               # username for dashboard login
DASHBOARD_PASSWORD=your_dashboard_pass  # set this — protects /auth

3. Run the server

node dist/todo-index.js

4. Authenticate

Open https://todo-mcp.yourdomain.com in your browser, enter your dashboard password, and click Connect Microsoft Account. After OAuth completes, tokens are saved on the server.

5. Connect your AI client

The dashboard shows ready-to-copy commands. Or manually:

Claude Code:

claude mcp add --transport http mstodo https://todo-mcp.yourdomain.com/mcp \
  --header "Authorization: Bearer your_api_key"

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mstodo": {
      "url": "https://todo-mcp.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer your_api_key" }
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "mstodo": {
      "url": "https://todo-mcp.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer your_api_key" }
    }
  }
}

Database

The list registry is stored in SQLite by default — a lists.db file created on first run, nothing to configure. Set DATABASE_URL and it uses Postgres instead.

# SQLite (default) — optional custom path
LIST_DB_PATH=/data/lists.db

# Postgres — set this and the SQLite file is ignored entirely
DATABASE_URL=postgres://user:password@host:5432/dbname

For hosted Postgres (Neon, Supabase, RDS) whose certificate chain Node will not verify by default, set DATABASE_SSL=no-verify. The connection stays encrypted; only chain validation is skipped.

OAuth tokens are not in the database — they stay in tokens.json (MSTODO_TOKEN_FILE), so the server still needs a persistent path for that file either way.

Sharing a database with other applications

Every table this server creates can be namespaced with a prefix, so one Postgres database can host this alongside your other apps:

DB_TABLE_PREFIX=mstodo_

That yields mstodo_lists and mstodo_schema_migrations. The prefix deliberately covers the migration bookkeeping table too — without it, two apps each using a bare schema_migrations would corrupt each other's version history and silently skip migrations. It must match a plain identifier pattern (letters, digits and underscores, not starting with a digit); anything else is rejected at startup rather than interpolated into SQL.

The prefix is empty by default, which leaves existing lists.db files working untouched.

Migrations

Migrations are plain .sql files under migrations/<dialect>/, applied in filename order and recorded in <prefix>schema_migrations.

They run automatically on startup and are a no-op once the schema is current, so a normal deploy needs no extra step. To run them yourself instead:

npm run migrate                # apply anything outstanding
AUTO_MIGRATE=false npm start   # and stop the server from doing it

Adding a migration means dropping 002_whatever.sql into both migrations/postgres/ and migrations/sqlite/. Use {{prefix}} wherever a table name appears — the runner substitutes it:

ALTER TABLE {{prefix}}lists ADD COLUMN color TEXT;

Each migration is applied in a transaction together with its version row, so a failure part-way leaves neither a half-built schema nor a version record claiming success.

Docker

Images are published for linux/amd64 and linux/arm64 to Docker Hub and GHCR.

There is no release process — main is the release, and every push to it rebuilds latest. The sha- tags are there so a deployment can be pinned or rolled back without one.

docker pull spacecentre/microsoft-todo-mcp-server-self-hosted:latest

services:
  todo-mcp:
    image: spacecentre/microsoft-todo-mcp-server-self-hosted:latest
    restart: unless-stopped
    env_file: .env
    volumes:
      - todo_data:/data
    ports:
      - "3001:3001"

volumes:
  todo_data:

The image defaults MSTODO_TOKEN_FILE and LIST_DB_PATH into /data, so one volume covers everything that has to survive a container recreate. On Postgres, lists.db goes unused and the volume holds only tokens.json — which still has to persist, or you re-authenticate after every deploy.

Migrations run on boot, so upgrading is docker compose pull && docker compose up -d with no extra step.

It runs as the non-root node user and ships a HEALTHCHECK against /health, the one route exempt from the API key so it works whether or not MCP_API_KEY is set.

Building it yourself

docker build -t todo-mcp .

Security

Always set DASHBOARD_PASSWORD. Without it, anyone who knows your URL can visit the dashboard and trigger an OAuth flow that overwrites your tokens. DASHBOARD_USERNAME defaults to admin.

MCP Tools

Task Lists

Tasks

Checklist Items

Other

License

MIT — see LICENSE