# microsoft-planner-mcp

Lightweight MCP (Model Context Protocol) server for Microsoft Planner that uses `az rest` for authentication instead of complex OAuth flows.

## What This Is

A minimal MCP server that enables Claude Code to interact with Microsoft Planner tasks directly. It leverages Azure CLI's existing authentication (`az login`) to make Graph API calls, eliminating the need for app registrations or token management.

## Prerequisites

- **Node.js** (v18 or later)
- **Azure CLI** installed and authenticated:
  ```bash
  az login
  ```

## Installation

```bash
git clone https://github.com/vyente-ruffin/microsoft-planner-mcp.git
cd microsoft-planner-mcp
npm install
npm run build
```

## Usage with Claude Code

Add the MCP server to Claude Code:

```bash
claude mcp add microsoft-planner-mcp node /path/to/microsoft-planner-mcp/dist/index.js
```

Or add directly to your MCP settings file:

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

## Available Tools

| Tool | Description |
|------|-------------|
| `list-plans` | List all Planner plans accessible to the current user |
| `list-buckets` | List all buckets in a plan |
| `list-tasks` | List all tasks in a Planner plan |
| `get-task` | Get details of a specific task |
| `get-task-details` | Get extended task details (description, checklist, references) |
| `create-task` | Create a new task in a plan |
| `update-task` | Update task properties (title, progress, assignments, categories) |
| `update-task-details` | Update task description (supports GitHub links) |
| `delete-task` | Delete a Planner task |

## Claude Code Agent (Optional)

For enhanced automation, create a Claude Code agent at `~/.claude/agents/microsoft-planner.md` with:

- **Auto-assignment**: Automatically assign tasks to a default user
- **Auto-labeling**: Apply default categories/labels to tasks
- **Status Intelligence**: Infer task bucket and progress from conversation context
- **GitHub Integration**: Include repository links in task descriptions

See the [agent template](https://github.com/vyente-ruffin/microsoft-planner-mcp/wiki/Agent-Configuration) for configuration details.

## Finding Your IDs

To use the MCP tools, you'll need your Planner Plan ID and Bucket IDs:

1. Use `list-plans` to discover all accessible plans and their IDs
2. Use `list-buckets` with your Plan ID to get bucket IDs
3. Or find your Plan ID from the Planner web URL: `https://tasks.office.com/...planId=YOUR_PLAN_ID`

## Example Usage

Once configured, use natural language with Claude Code:

```
"List all my planner plans"
"List all tasks in the planner"
"Create a task called 'Review PR #123' in the backlog bucket"
"Mark task XYZ as complete"
"Add a description with the GitHub PR link to the task"
```

## How It Works

This server uses `az rest` to make Microsoft Graph API calls. The Azure CLI handles all authentication, so as long as you're logged in with `az login`, the server can access Planner data your account has permissions for.

All Planner operations that require ETags (update, delete) automatically fetch the current ETag before making changes.

## License

ISC