kairos-mcp

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.

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.

• Entra admin centre → App registrations → New registration. Single tenant is fine. No redirect URI needed.
• Authentication → Settings → enable Allow public client flows. Device code sign-in needs this. No client secret is used anywhere.
• API permissions → Microsoft Graph → Delegated → add Tasks.ReadWrite ("Create, read, update and delete user's tasks and projects"). Nothing else.
• 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.