Skip to main content
Glama

mcp-planner

MCP server for Microsoft Planner via the Microsoft Graph API. Find groups and plans, list buckets and tasks, and create, update, assign, complete, or delete tasks — including descriptions and checklists — with Planner's ETag concurrency handled automatically.

Sibling project to mcp-itglue and mcp-connectwise-psa — same architecture.

Tools

Tool

Description

planner_search_groups

Find Microsoft 365 groups (Teams) by name → group ID

planner_find_user

Find a user by name/UPN → user ID for assignments

planner_list_plans

List plans owned by a group

planner_get_plan

Plan + its buckets

planner_create_bucket

Create a bucket in a plan

planner_list_tasks

Tasks in a plan or bucket (filter by assignee, open/completed)

planner_list_user_tasks

All tasks assigned to a user, across plans

planner_get_task

Task with description and checklist

planner_create_task

Create task (bucket, due date, priority, assignees, description)

planner_update_task

Update title/bucket/due/priority/progress/assignees

planner_update_task_details

Update description; add or (un)check checklist items

planner_delete_task

Permanently delete a task

graph_find_endpoint †

Search a curated catalog of the /planner, /groups, /users Graph surface

graph_get †

Read-only GET for any Graph v1.0 path under /planner, /groups, /users

† Advanced toolset (opt-in, off by default) — an escape hatch for Graph surface the curated tools don't wrap. Enable with PLANNER_ADVANCED_TOOLSET=true or --advanced. graph_get is verb-locked to GET, rejects /beta, and only reaches the three path prefixes above, so a shared app registration's other permissions (e.g. mail) stay out of reach.

Related MCP server: mcp-planner-premium

Setup

1. Entra ID app registration

  1. Entra admin center → App registrations → New registration

  2. API permissions → Application permissions → add Tasks.ReadWrite.All, GroupMember.Read.All, User.Read.All → Grant admin consent

  3. Certificates & secrets → New client secret — note the value

2. Run

MS_TENANT_ID=<tenant> MS_CLIENT_ID=<client-id> MS_CLIENT_SECRET=<secret> npx -y mcp-planner

Claude Code:

claude mcp add planner --env MS_TENANT_ID=<tenant> --env MS_CLIENT_ID=<client-id> --env MS_CLIENT_SECRET=<secret> -- npx -y mcp-planner

HTTP mode

npx -y mcp-planner --transport http --port 3000

Sessions authenticate per-request (BYOK) with x-ms-tenant-id + x-ms-client-id plus either x-ms-client-secret (app-only) or x-ms-refresh-token (delegated — see below), or fall back to the MS_* environment credentials when set. When both a secret and a refresh token arrive, the refresh token wins (header-overlay proxies can add but not remove headers). Health probe at GET /health.

Delegated mode — act as the signed-in user

App-only sessions act as the app registration; delegated sessions act as a user: their Planner permissions apply and every write is attributed to them.

  1. A separate, public app registration: Authentication → Allow public client flows → Yes; API permissions → Delegated Tasks.ReadWrite, Group.Read.All, User.ReadBasic.All (+ admin consent where the tenant requires it).

  2. Each user signs in once via the device-code helper and keeps the printed refresh token:

node scripts/device-login.mjs --tenant <tenant-id> --client <public-client-id>
  1. Use MS_REFRESH_TOKEN instead of MS_CLIENT_SECRET (stdio), or the x-ms-refresh-token header (HTTP). Behind the MCP gateway, register it as a personal credential (field x-ms-refresh-token).

The refresh token is a secret — it acts as you — and stays valid ~90 days past its last use; re-run the helper when it expires.

Docker

docker build -t mcp-planner .
docker run -p 3000:3000 -e MS_TENANT_ID=... -e MS_CLIENT_ID=... -e MS_CLIENT_SECRET=... mcp-planner

Access model

No MCP-level role gating: the Entra app registration's granted Graph permissions are the access control. Point sessions at different app registrations (BYOK headers) to scope what they can do.

Notes

  • Planner requires an If-Match ETag on every update/delete — the tools fetch the current resource and pass its ETag automatically. On a 412 (concurrent change), just retry.

  • Priority mapping: urgent=1, important=3, medium=5, low=9 (Graph uses 0–10).

  • Progress: not started (0), in progress (50), completed (100).

Development

npm install
npm run dev        # stdio
npm run dev:http   # http
npm test
npm run build
npm run bundle     # Claude Desktop .mcpb

License

MIT

Available Tools

12 tools
planner_create_bucketCreate a BucketA

Create a new bucket (column) in a plan.

Inputs: name (required), plan_id (required).

planner_create_taskCreate a TaskA

Create a Planner task in a plan. Optionally set the bucket, due date, priority, assignees, and a description.

Inputs: title (required), plan_id (required), due_date, priority, +3 more.

planner_delete_taskDelete a TaskA
DestructiveIdempotent

Permanently delete a Planner task. This cannot be undone.

Inputs: task_id (required).

planner_find_userFind a UserA
Read-onlyIdempotent

Find a user by display name or UPN/email to get the user ID needed for task assignments and planner_list_user_tasks.

Inputs: query (required), top, response_format.

planner_get_planGet a Plan with its BucketsA
Read-onlyIdempotent

Get a Planner plan and its buckets. Bucket IDs are needed to create or move tasks.

Inputs: plan_id (required), response_format.

planner_get_taskGet a Task with DetailsA
Read-onlyIdempotent

Get a Planner task including its description and checklist. Also returns the etags needed by update tools (updates fetch them automatically).

Inputs: task_id (required), response_format.

planner_list_plansList Plans in a GroupA
Read-onlyIdempotent

List all Planner plans owned by a Microsoft 365 group. Get the group ID from planner_search_groups.

Inputs: group_id (required), response_format.

planner_list_tasksList Tasks in a Plan or BucketA
Read-onlyIdempotent

List Planner tasks in a plan (or a single bucket). Optionally filter by assignee user ID or open/completed state.

Inputs: top, plan_id, bucket_id, assigned_to, +2 more.

planner_list_user_tasksList a User's TasksA
Read-onlyIdempotent

List all Planner tasks assigned to a user across every plan they participate in. Get the user ID from planner_find_user.

Inputs: user_id (required), top, response_format, include_completed.

planner_search_groupsSearch Microsoft 365 GroupsA
Read-onlyIdempotent

Search Microsoft 365 groups (Teams) by display name. Use this first to find the group ID required by planner_list_plans.

Inputs: name_contains (required), top, response_format.

planner_update_taskUpdate a TaskA
Idempotent

Update a Planner task: title, bucket (move), due date, priority, progress (not started / in progress / completed), or assignees. Fetches the current etag automatically.

Inputs: task_id (required), title, due_date, priority, +4 more.

planner_update_task_detailsUpdate Task Description or ChecklistA
Idempotent

Update a task's description, add checklist items, or check/uncheck existing checklist items (item IDs come from planner_get_task).

Inputs: task_id (required), description, check_item_ids, uncheck_item_ids, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action. The only potential overlap between planner_list_tasks and planner_list_user_tasks is clearly separated by scope: one lists tasks within a plan/bucket, the other lists all tasks across plans for a user.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (search_groups, list_plans, create_bucket, update_task_details, etc.). No mixed conventions or vague verbs.

    Tool Count5/5

    12 tools is well-scoped for a Microsoft Planner server, covering discovery (groups, users), plan/bucket inspection, and full task lifecycle (list, get, create, update, delete) without bloat.

    Completeness4/5

    The task lifecycle is fully covered (create, read, update, delete, plus details updates). Minor gaps exist such as no update/delete bucket or plan creation, but these are secondary to the core Planner workflows and often outside the intended scope.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers