Microsoft Planner Server

An MCP server that exposes your Microsoft Planner tasks to MCP clients (Claude, GitHub Copilot, VS Code, and others). List your tasks grouped by bucket, drill into details/checklists/comments, and update task progress, all from your assistant.

Tools

Tool	What it does
get_planner_tasks	Tasks assigned to you, grouped by bucket. Filter by bucket/priority; with_details=true adds description, checklist, and comments.
update_planner_tasks	Set progress (not_started / in_progress / completed) for one or more tasks.
get_planner_buckets	List your bucket names.

Install

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env        # then edit .env

Authentication

This server talks to Microsoft Graph with delegated permissions (User.Read, Tasks.ReadWrite). Pick one of two methods via AUTH_METHOD in .env.

Method 1: device code (default, recommended)

Uses your own Azure app registration. One-time portal setup:

1. Microsoft Entra ID, then App registrations, then New registration.

2. Authentication: add a Mobile and desktop applications platform and enable Allow public client flows.

3. API permissions: add delegated Microsoft Graph permissions User.Read and Tasks.ReadWrite (and grant/consent for your account).

4. Put the IDs in .env:

   AUTH_METHOD=device
   CLIENT_ID=<application-client-id>
   TENANT_ID=<directory-tenant-id>
   

Then sign in once:

python login.py     # prints a URL + code; open it and sign in

MSAL caches a refresh token and the server refreshes access tokens silently.

Method 2: browser fallback (no admin, locked-down tenants)

⚠️ Read this first. This method drives a headless Chromium that replays Graph Explorer's sign-in, borrowing the Graph Explorer first-party client to obtain tokens. Use it only if your tenant blocks app consent and you have no admin access and no way to register an app. It is unsupported, depends on undocumented Graph Explorer behavior (and may break without notice), and may be against your organization's policies, so check before using it. When you can, use Method 1 instead.

pip install playwright && playwright install chromium chromium-headless-shell
# fetch the MSAL.js library used inside the browser:
mkdir -p vendor && curl -fsSL -o vendor/msal-browser.min.js \
  https://cdn.jsdelivr.net/npm/@azure/[email protected]/lib/msal-browser.min.js

.env:

AUTH_METHOD=browser
TENANT_ID=<directory-tenant-id>
[email protected]   # optional

Then:

python login.py     # opens a browser window; sign in + MFA once

The signed-in session is saved in .browser_profile/, and the server fetches tokens silently afterwards. Re-run login.py if the session ever lapses.

Connect an MCP client

Example (VS Code / Claude mcp.json-style config):

{
  "mcpServers": {
    "planner": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/planner_mcp_server.py"]
    }
  }
}

Use with Claude

Once setup and sign-in are done, the simplest way is the Claude Code CLI. Register the server in one command (use absolute paths):

claude mcp add planner /absolute/path/to/.venv/bin/python /absolute/path/to/planner_mcp_server.py

That's it. Start claude and just ask in plain language, for example:

• "What are my Planner tasks?"
• "Show me the details of my in-progress tasks."
• "Mark Write the report as completed."

Claude calls the tools for you. Run claude mcp list to confirm it's connected, or /mcp inside Claude Code to see its status.

For the Claude desktop app, add the same mcpServers block shown above to your claude_desktop_config.json (Settings, then Developer, then Edit Config) and restart the app.

Configuration reference

Variable	Default	Notes
AUTH_METHOD	device	device or browser
CLIENT_ID	(none)	Your app's client ID (device method)
TENANT_ID	organizations	Your tenant GUID
GRAPH_SCOPES	User.Read Tasks.ReadWrite	Space-separated delegated scopes
GRAPH_LOGIN_HINT	(none)	Pre-fill the sign-in account

Security notes

Never commit .env, .token_cache.json, .msal_cache.json, or .browser_profile/, since they hold credentials. They are in .gitignore.

Disclaimer

This is an independent, community project. It is not affiliated with, endorsed by, or sponsored by Microsoft. "Microsoft", "Microsoft Planner", and "Microsoft Graph" are trademarks of Microsoft Corporation, used here only to describe interoperability.

License

MIT. See LICENSE.