Microsoft Planner MCP

A small Node.js MCP server that integrates with Microsoft Planner using the Microsoft Graph API.

Features

Prerequisites

1. An Azure App Registration with the following Application permissions in Microsoft Graph:
   • Group.Read.All
   • Tasks.ReadWrite.All
   • User.Read.All
2. A Client Secret generated for the App Registration.
3. Node.js 18 or newer.

Setup

1. Install dependencies:

npm install

1. Copy and edit the environment file:

cp .env.example .env

Fill these environment variables in .env:

CLIENT_ID=<App Registration Client ID>
TENANT_ID=<Azure AD Tenant ID>
CLIENT_SECRET=<Client Secret>
# Optional defaults used by some tools
GROUP_ID=<optional default group id>
PLAN_ID=<optional default plan id>

1. Build the project:

npm run build

Usage

Run the server as an MCP stdio server. Example mcp.json entry:

{
  "servers": {
    "planner": {
      "command": "node",
      "args": ["/absolute/path/to/planner-mcp-server/dist/index.js"],
      "env": {
        "CLIENT_ID": "...",
        "TENANT_ID": "...",
        "CLIENT_SECRET": "...",
        "GROUP_ID": "...", // optional default group id for tools that require it
        "PLAN_ID": "..." // optional default plan id for tools that require it
      }
    }
  }
}

For local development you can run:

npm run dev

Testing

Tests are written with Vitest and live in src/__tests__/.

Run the test suite:

# Run once
npm test

# Watch mode (re-runs on file changes)
npm run test:watch

# With coverage report
npm run test:coverage

No real Azure credentials are needed to run the tests — the Microsoft Graph client is fully mocked.

Project Structure

src/
  graph-client.ts    # Creates an authenticated Microsoft Graph client
  planner-service.ts # Service implementing Planner CRUD operations
  utils.ts           # Response helpers (ok / err)
  index.ts           # Entry point — registers tools and starts the MCP server
  __tests__/
    utils.test.ts            # Unit tests for response helpers
    planner-service.test.ts  # Unit tests for PlannerService
    graph-client.test.ts     # Unit tests for createGraphClient and auth setup

Example Prompts

• "List the plans in group abc123"
• "Create a task 'Review document' in plan xyz456 with urgent priority and due 2025-04-01"
• "Mark task task789 as completed"
• "Update task task789 description to 'Document reviewed and approved'"