The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Kairos listing page.
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.
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.
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.
Tasks.ReadWrite ("Create, read, update and delete user's tasks and
projects"). Nothing else.Then add kairos to your MCP client:
Sign in once, either from a terminal:
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.
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.
| 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.
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.
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.
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.
~/.config/kairos/DISABLED, or set
KAIROS_DISABLED=1, and every tool refuses.~/.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.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: " !").
MIT — see LICENSE.