Planner MCP

A remote Model Context Protocol server that lets Claude read, create, assign and close Microsoft Planner tasks for a small team.

Claude's built in Microsoft 365 connector covers Outlook, Teams chat and SharePoint, but not Planner tasks. This fills that gap.

Setup instructions are in SETUP.md.

What it does

Ask Claude to turn a brief into tasks and it does, assigned to the right people:

Turn the Friday notes into Planner tasks. Aysyal takes the social channels, I take the tracking work, everything due next Friday in the To do bucket.

Ask it what is going on and it answers from live data:

What is overdue in the marketing plan, and what is on Anton's plate this week?

Tools

Tool	Purpose
whoami	Which team member is connected, and which plans they can reach
list_plans	The plans this server can read and write
list_buckets	The columns in a plan
list_tasks	Tasks in a plan, filtered by assignee, bucket, status, overdue or due date
my_tasks	Open tasks for the connected person, across every plan
get_task	One task in full, including notes, checklist and links
create_task	One task, with assignees, due date, priority, notes, checklist, labels and a link
create_tasks	A batch, with shared defaults. This is the one to use for a brief
update_task	Change any field on an existing task
assign_task	Add people, or replace the whole assignee list
unassign_task	Take people off without deleting
complete_task	Mark done
delete_task	Remove permanently, and it insists on confirmation
find_person	Search the directory for the right email address

How it is built

Node 20 or newer, Express, and nothing else. One dependency total, so a deploy is never held up by a transitive package.

App only auth to Microsoft

The server talks to Microsoft Graph with the client credentials flow, using Tasks.ReadWrite.All, Group.Read.All and User.Read.All application permissions. There is no user token in the picture, so a password change or an expired session never breaks it. The only credential with an expiry date is the client secret, and that is on a 24 month clock.

Nobody is hardcoded

Assignees arrive as email addresses and are resolved against Entra ID at call time, with a one hour cache. The lookup falls back to searching mail and proxyAddresses when an address is not somebody's sign in name, which is the case for aliases. Adding a colleague to the team needs no code change and no deploy.

Before assigning, the server checks whether the person is in the Microsoft 365 group behind the plan. Planner accepts assignments to outsiders without complaining and then never shows them the task, so the server warns instead of letting that pass silently.

Its own OAuth server, so Connect asks for a password

Pressing Connect in Claude opens a login page served by this app. Type a work email and the team password and you are in. Behind that page is a small OAuth 2.1 authorization server: dynamic client registration, PKCE with S256 required, authorization code flow, refresh tokens.

Every piece of OAuth state is a signed token rather than a database row. Client registrations, authorization codes, access tokens and refresh tokens are all HMAC signed with JWT_SECRET. Three consequences worth knowing:

• No database to run or back up.
• A redeploy or a Railway restart does not disconnect anybody. This is covered by a test.
• Rotating JWT_SECRET disconnects everybody at once, which is the emergency brake.

Failed logins are rate limited to ten per address per fifteen minutes. Password comparison is constant time.

Planner's awkward corners, handled

• Two ETags per task. The task body and the task detail pane are separate objects with separate versions, and Planner rejects a write without the current one. Every update reads before it writes.
• Basic plans only. Planner Premium plans are not reachable through this API, so no Premium licence is needed or useful.
• Dates. A bare 2026-08-15 is stored at midday UTC, which keeps the date correct in both Amsterdam and Sofia.
• Labels by name. Pass SEO rather than category1. The server reads the plan's label names and translates.
• Rate limits. 429 and 503 are retried with backoff, honouring Retry-After.

Tests

npm test

Starts a fake Microsoft Graph, spawns the real server, walks the entire OAuth flow by hand, then connects with the official MCP client and calls every tool. Ends with 91 checks passed. It never touches the real tenant.

Layout

src/
  index.js        Express app and routes
  config.js       Environment loading and validation
  auth.js         OAuth 2.1 authorization server and bearer verification
  jwt.js          HS256 signing, PKCE, constant time password comparison
  login-page.js   The password gate and the status page
  graph.js        Microsoft Graph client: tokens, retries, ETags
  people.js       Email address to Entra object ID, with alias fallback
  planner.js      Plans, buckets, tasks, details, labels
  tools.js        MCP tool definitions and output formatting
  mcp.js          JSON-RPC over the Streamable HTTP transport
test/
  mock-graph.js   Fake Microsoft Graph
  smoke-test.js   End to end test