{
  "markdown": "# mcp-planner\n\nMCP 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.\n\nSibling project to [mcp-itglue](https://github.com/mspstack/mcp-itglue) and [mcp-connectwise-psa](https://github.com/mspstack/mcp-connectwise-psa) — same architecture.\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `planner_search_groups` | Find Microsoft 365 groups (Teams) by name → group ID |\n| `planner_find_user` | Find a user by name/UPN → user ID for assignments |\n| `planner_list_plans` | List plans owned by a group |\n| `planner_get_plan` | Plan + its buckets |\n| `planner_create_bucket` | Create a bucket in a plan |\n| `planner_list_tasks` | Tasks in a plan or bucket (filter by assignee, open/completed) |\n| `planner_list_user_tasks` | All tasks assigned to a user, across plans |\n| `planner_get_task` | Task with description and checklist |\n| `planner_create_task` | Create task (bucket, due date, priority, assignees, description) |\n| `planner_update_task` | Update title/bucket/due/priority/progress/assignees |\n| `planner_update_task_details` | Update description; add or (un)check checklist items |\n| `planner_delete_task` | Permanently delete a task |\n| `graph_find_endpoint` † | Search a curated catalog of the /planner, /groups, /users Graph surface |\n| `graph_get` † | Read-only GET for any Graph v1.0 path under /planner, /groups, /users |\n\n† 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.\n\n## Setup\n\n### 1. Entra ID app registration\n\n1. [Entra admin center](https://entra.microsoft.com) → App registrations → **New registration**\n2. API permissions → **Application permissions** → add `Tasks.ReadWrite.All`, `GroupMember.Read.All`, `User.Read.All` → **Grant admin consent**\n3. Certificates & secrets → **New client secret** — note the value\n\n### 2. Run\n\n```bash\nMS_TENANT_ID=<tenant> MS_CLIENT_ID=<client-id> MS_CLIENT_SECRET=<secret> npx -y mcp-planner\n```\n\nClaude Code:\n\n```bash\nclaude mcp add planner --env MS_TENANT_ID=<tenant> --env MS_CLIENT_ID=<client-id> --env MS_CLIENT_SECRET=<secret> -- npx -y mcp-planner\n```\n\n### HTTP mode\n\n```bash\nnpx -y mcp-planner --transport http --port 3000\n```\n\nSessions 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`.\n\n### Delegated mode — act as the signed-in user\n\nApp-only sessions act as the app registration; delegated sessions act as a **user**: their Planner permissions apply and every write is attributed to them.\n\n1. 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).\n2. Each user signs in once via the device-code helper and keeps the printed refresh token:\n\n```bash\nnode scripts/device-login.mjs --tenant <tenant-id> --client <public-client-id>\n```\n\n3. 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`).\n\nThe 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.\n\n### Docker\n\n```bash\ndocker build -t mcp-planner .\ndocker run -p 3000:3000 -e MS_TENANT_ID=... -e MS_CLIENT_ID=... -e MS_CLIENT_SECRET=... mcp-planner\n```\n\n## Access model\n\nNo 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.\n\n## Notes\n\n- 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.\n- Priority mapping: urgent=1, important=3, medium=5, low=9 (Graph uses 0–10).\n- Progress: not started (0), in progress (50), completed (100).\n\n## Development\n\n```bash\nnpm install\nnpm run dev        # stdio\nnpm run dev:http   # http\nnpm test\nnpm run build\nnpm run bundle     # Claude Desktop .mcpb\n```\n\n## License\n\nMIT\n",
  "bytes": 4829,
  "sha": "04710409c63271c9d033170b44a06866c4155396b916316787353fe009d5600e",
  "repo_slug": "selic/mcp-planner",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_selic_mcp_planner_2f1d5e6c/readme"
}