Planner MCP Server

A Model Context Protocol (MCP) server that enables Claude to interact with Microsoft Planner through the Microsoft Graph API.

Features

• Authentication: OAuth 2.0 device code flow for secure authentication

• Plans Management: List and view Planner plans

• Buckets Management: List, create, and manage buckets within plans

• Tasks Management: Create, update, delete, and view tasks

• Checklists: Add, update, and remove checklist items on tasks

• Token Persistence: Stores access tokens across server restarts

Related MCP server: Microsoft Planner MCP

Prerequisites

• Node.js 18+ or newer

• npm or yarn

• Microsoft account with access to Planner

Installation

1. Clone or download this repository

2. Install dependencies:

cd planner-mcp
npm install

3. Build the project:

npm run build

Authentication

Before using the Planner tools, you need to authenticate:

1. Start the authentication flow by calling the auth_start tool

2. Visit the displayed verification URL

3. Enter the provided code

4. Sign in with your Microsoft account

5. Use the auth_poll tool to check if authentication is complete

The access token will be saved locally and reused for future sessions.

Configuration

Option 1: Using CLI (Recommended)

claude mcp add --transport stdio planner node /path/to/planner-mcp/build/index.js

Option 2: Manual Configuration

Add this server to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "planner": {
      "command": "node",
      "args": ["/path/to/planner-mcp/build/index.js"]
    }
  }
}

Note: Replace /path/to/planner-mcp/build/index.js with the actual path to your cloned repository.

Available Tools

Authentication Tools

• auth_start: Start the Planner authentication flow (device code)

• auth_poll: Check if authentication is complete

Plan Tools

• list_plans: List all Microsoft Planner plans for the current user

• get_plan: Get detailed information about a specific plan

Bucket Tools

• list_buckets: List all buckets in a plan

• create_bucket: Create a new bucket in a plan

Task Tools

• list_tasks: List tasks in a plan or bucket with filtering options (priority, due date, status, etc.)

• get_task: Get detailed information about a specific task

• create_task: Create a new task in a bucket with title, description, priority, and due date

• update_task: Update an existing task (title, description, priority, bucket, due date, checklist, etc.)

• delete_task: Delete a task

Checklist parameter (on create_task and update_task): pass checklist as an object keyed by item ID, same style as assignments:

• To add an item, use any unique string as the key with {"title": "...", "isChecked": false}

• To update an item, use its existing item ID (from get_task/list_tasks with includeDetails: true) with just the fields to change

• To remove an item, set its ID's value to null

Example:

{
  "taskId": "your-task-id",
  "checklist": {
    "buy-milk": { "title": "Buy milk", "isChecked": false },
    "existing-item-id-from-get-task": { "isChecked": true },
    "item-id-to-remove": null
  }
}

Checklist items are visible on any task fetched via get_task or list_tasks with includeDetails: true (under details.checklist, keyed by item ID).

Priority Levels:

• 1 = Urgent (highest priority)

• 3 = Important (high priority)

• 5 = Medium (normal priority)

• 9 = Low (lowest priority)

Required Permissions

The Microsoft Graph API requires the following permissions for Planner:

• Group.Read.All - To list plans and buckets

• Tasks.ReadWrite - To read, create, update, and delete tasks

Example Workflows

Create a new task

1. List plans: list_plans

2. List buckets in a plan: list_buckets with the plan ID

3. Create a task: create_task with plan ID, bucket ID, title, and priority (1=urgent, 3=important, 5=medium, 9=low)

Example:

{
  "planId": "your-plan-id",
  "bucketId": "your-bucket-id",
  "title": "Complete project proposal",
  "description": "Write and submit the Q1 project proposal",
  "priority": 1,
  "dueDateTime": "2026-03-30T17:00:00Z"
}

Move a task to another bucket

1. Get task details: get_task

2. Update task: update_task with the new bucket ID

Filter tasks by priority

1. List tasks with priority filter: list_tasks with plan ID and priority parameter

Example:

{
  "planId": "your-plan-id",
  "priority": 1
}

This will show only urgent tasks (priority 1).

Update task due date

1. Get task details: get_task

2. Update task: update_task with the new due date in ISO 8601 format (e.g., "2025-12-31T23:59:59Z")

Troubleshooting

Authentication Issues

If authentication fails, try these steps:

1. Delete the .access-token.txt file

2. Call auth_start again

3. Make sure you're using a Microsoft account that has access to Planner

"Not authenticated" Error

If you get a "Not authenticated" error:

1. Make sure you've completed the authentication flow

2. Check that the .access-token.txt file exists and contains a valid token

3. If the token has expired, run auth_start again

Permission Errors

If you get permission errors:

• Make sure your Microsoft account has access to the specified plan

• Check that the required permissions are granted in your Azure AD app

Development

Build

npm run build

Watch mode

npm run watch

Start server

npm start

License

ISC

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.