Skip to main content
Glama

kairos

A Microsoft Planner MCP server that writes tasks.

An agent creates tasks and buckets in your Planner plans, lists what is there, and marks tasks complete. Sign-in is delegated device-code against your own Entra app with the single Graph scope Tasks.ReadWrite; the token reaches only the plans you are a member of and nothing else in the tenant.

kairos is the sibling of iris, the mail server that cannot send. They are deliberately separate. iris's value is an absent capability; a Planner writer's value is the write itself. Creating a task creates a task. Completing one completes one. kairos does not pretend otherwise, so read what it can do before you install it.


Install

uvx kairos-mcp        # run without installing
pip install kairos-mcp

Python 3.10 or newer. macOS ships Python 3.9, which is too old — mcp requires 3.10+. Use uv (it comes with uvx and manages its own Python), or install a current Python with Homebrew (brew install python@3.12). The system python3 on macOS will not work.

Related MCP server: microsoft-tasks-mcp

Setup

You must register your own Entra application. There is no shared app registration and no hosted service — kairos talks directly from your machine to your tenant. A shared app would mean trusting someone else's client ID with write access to your plans.

  1. Entra admin centre → App registrations → New registration. Single tenant is fine. No redirect URI needed.

  2. Authentication → Settings → enable Allow public client flows. Device code sign-in needs this. No client secret is used anywhere.

  3. API permissions → Microsoft Graph → Delegated → add Tasks.ReadWrite ("Create, read, update and delete user's tasks and projects"). Nothing else.

  4. Copy the Application (client) ID and Directory (tenant) ID. Neither is a secret.

Then add kairos to your MCP client:

{
  "mcpServers": {
    "kairos": {
      "command": "uvx",
      "args": ["kairos-mcp"],
      "env": {
        "KAIROS_CLIENT_ID": "<application (client) id>",
        "KAIROS_TENANT_ID": "<directory (tenant) id>",
        "KAIROS_DEFAULT_PLAN": "Development"
      }
    }
  }
}

Sign in once, either from a terminal:

KAIROS_CLIENT_ID=... KAIROS_TENANT_ID=... uvx kairos-mcp auth

or from inside the MCP client: call kairos_login, open the URL, enter the code, then call kairos_login_finish. Either way the token cache lands in ~/.config/kairos/token_cache.json, mode 600, and refreshes silently from then on.

KAIROS_DEFAULT_PLAN is optional. Without it, every call must name a plan — unless your account can see exactly one, in which case that one is used.

Clients

kairos is a local stdio MCP server: your MCP client launches it as a child process on the same machine. It works with any client that supports local stdio servers — Claude Desktop, Cursor, the Grok CLI and others. It does not work with clients that only accept remote MCP connectors over HTTP.

Tools

Tool

What it does

kairos_login

Starts device-code sign-in, returns a URL and a code

kairos_login_finish

Completes sign-in; safe to call repeatedly while you type the code

kairos_auth_status

Who is signed in, whether Graph is reachable, how many plans are visible

list_planner_plans

Every plan you can see, with its buckets and IDs (cached a few minutes; refresh=true to re-read)

create_planner_task

Creates a task: title, optional notes, plan, bucket, due_on (YYYY-MM-DD). Returns the task ID and a URL

create_planner_bucket

Creates a bucket in a plan. Idempotent — an existing bucket of that name is returned, not duplicated

list_planner_tasks

Tasks in a plan (or plan="*" for all), optionally one bucket, open only by default

complete_planner_task

Marks a task 100% by task_id, or by title when the match is unique. reopen=true undoes it

Plans and buckets are matched by name, case-insensitively, or by ID. A partial name works when it is unambiguous. Omit bucket and the plan's first bucket is used.

Completing by title refuses ambiguity

complete_planner_task(title="deploy") searches open tasks in the plan. One match: it completes it. Two or more: it stops and lists them with IDs so you can re-call with the exact task_id. It never picks one for you.

CLI

kairos-mcp            run the MCP server on stdio (what your client launches)
kairos-mcp auth       interactive device-code sign-in
kairos-mcp status     who is signed in, is Graph reachable
kairos-mcp logout     remove the token cache

Re-authenticating

A refresh token stops working after a password change, an admin revocation, or long disuse. Every tool then returns a message that says so and how to fix it: kairos-mcp auth in a terminal, or kairos_login → kairos_login_finish from the client. Nothing else needs to change.

What it can and cannot do

Can: create tasks and buckets in any plan you are a member of; set a task's notes and due date at creation; list plans, buckets and tasks; mark a task complete or reopen it.

Cannot: delete anything — there is no delete tool, and the design keeps it that way. Assign people. Set priority, labels, checklists or attachments. Edit an existing task's title, notes or due date. See plans you are not a member of.

Tasks.ReadWrite is the narrowest Graph scope that permits creating a Planner task. It also permits reading and updating every task in every plan you belong to, and in principle deleting them. kairos does not expose delete, but the token could — the boundary is this code, not Microsoft's consent screen. If that distinction matters to you, it should; see SECURITY.md.

Other controls

  • Kill switch — create ~/.config/kairos/DISABLED, or set KAIROS_DISABLED=1, and every tool refuses.

  • Audit log — every write (login, create, complete, reopen) is appended to ~/.config/kairos/audit.log.

  • KAIROS_CONFIG_DIR moves the cache, log and kill-switch file elsewhere; KAIROS_TOKEN_CACHE and KAIROS_AUDIT_LOG override individual paths.

Graph notes, for the curious

A task's notes are not on the task; they live on a child details entity that Graph guards with an ETag. kairos creates the task, reads the details ETag, then PATCHes with If-Match. Completion is the same dance on the task itself. Planner throttles hard, so every call retries on 429 with Retry-After and there is a short pause between chained calls. New tasks and buckets are pinned to the top of their column (orderHint: " !").

License

MIT — see LICENSE.

Available Tools

8 tools
complete_planner_taskA

Mark a Planner task complete (or reopen it). This is a real write.

Give either task_id (exact, preferred) or title. A title is matched against OPEN tasks only (COMPLETED tasks when reopen=true); if it matches more than one, this refuses and lists the candidates rather than guessing.

Args: task_id: Exact Planner task ID. Preferred when known. title: Task title or a distinctive part of it. Used only if task_id is empty. plan: Plan to search when matching by title. Empty uses the default plan. reopen: Set true to undo a completion (sets 0%) instead.

Inputs: plan, title, reopen, task_id. Returns: result

create_planner_bucketA

Create a bucket (board column) in a Planner plan. Idempotent: if a bucket with that name already exists (case-insensitive) its ID is returned and nothing is created.

Args: bucket_name: Name of the bucket. plan: Plan name or ID. Empty uses KAIROS_DEFAULT_PLAN / the only plan.

Inputs: bucket_name (required), plan. Returns: result

create_planner_taskA

Create a task in Microsoft Planner. This is a real write: the task exists the moment this returns.

Args: title: Short, action-oriented task title (required). notes: Longer context for the task body (Planner "Notes"). plan: Plan name (case-insensitive) or ID. Empty uses KAIROS_DEFAULT_PLAN, or the only plan if the account has exactly one. bucket: Bucket within the plan, by name or ID. Empty uses the plan's first bucket. Call list_planner_plans to see what exists. due_on: Due date as YYYY-MM-DD, or empty for none.

Inputs: title (required), plan, notes, bucket, +1 more. Returns: result

kairos_auth_statusA

Report whether kairos is signed in, as whom, whether Graph is reachable, and how many plans are visible.

Inputs: no named parameters. Returns: result

kairos_loginA

Start a device-code sign-in to Microsoft 365. Returns a URL and a code for the human to enter in a browser; then call kairos_login_finish() to complete. Only needed once, or after the refresh token lapses (for example after a password change).

Inputs: no named parameters. Returns: result

kairos_login_finishA

Complete a device-code sign-in started with kairos_login(). Call after entering the code in the browser. Waits up to ~60s; if the code has not been entered yet, it says so and can simply be called again.

Inputs: no named parameters. Returns: result

list_planner_plansA

List the Planner plans this account can see, each with its buckets and IDs. Results are cached for a few minutes; pass refresh=true to force a re-read (for example after someone added a bucket in the Planner UI).

Inputs: refresh. Returns: result

list_planner_tasksA

List Planner tasks with their IDs, so a task can be referenced or completed.

Args: plan: Plan name or ID. Empty uses KAIROS_DEFAULT_PLAN / the only plan. Pass "" to list every plan the account can see. bucket: Optional bucket name to filter by (ignored with plan=""). include_completed: Include tasks already at 100%. Defaults to open only.

Inputs: plan, bucket, include_completed. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool maps to a distinct action/resource: auth bootstrap/finish/status, plan listing, task creation, bucket creation, task listing, and task completion. The two-step login flow is clearly sequenced, and there is no meaningful overlap between tools.

    Naming Consistency4/5

    Most names follow a clear verb_noun snake_case pattern (list_planner_plans, create_planner_task, complete_planner_task). Minor inconsistency: auth tools use a kairos_ prefix while planner tools do not, and kairos_login_finish is a verb+adverb rather than a noun, but the overall pattern remains readable.

    Tool Count5/5

    Eight tools is well-scoped for an authentication flow plus Planner task management. Each tool earns its place, and there are no redundant or overwhelming additions.

    Completeness3/5

    Core Planner workflows are covered: list plans, create buckets, create tasks, list tasks, and complete/reopen tasks. However, there is no way to update task details, delete a task or bucket, or fetch a single task in isolation, which leaves notable lifecycle gaps.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers