kairos
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kairos Create a task in the Development plan: "Review Q3 budget draft.""
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpPython 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.
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 author 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 |
| Starts device-code sign-in, returns a URL and a code |
| Completes sign-in; safe to call repeatedly while you type the code |
| Who is signed in, whether Graph is reachable, how many plans are visible |
| Every plan you can see, with its buckets and IDs (cached a few minutes; |
| Creates a task: |
| Creates a bucket in a plan. Idempotent — an existing bucket of that name is returned, not duplicated |
| Tasks in a plan (or |
| Marks a task 100% by |
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 cacheRe-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 setKAIROS_DISABLED=1, and every tool refuses.Audit log — every write (login, create, complete, reopen) is appended to
~/.config/kairos/audit.log.KAIROS_CONFIG_DIRmoves the cache, log and kill-switch file elsewhere;KAIROS_TOKEN_CACHEandKAIROS_AUDIT_LOGoverride 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 toolscomplete_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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Permissioned access to Outlook, OneDrive and Teams via the user's own Microsoft account
A graph-based task manager your agent can read and update: tasks, dependencies, blockers.
Your planner in every AI chat: tasks, calendar, docs, habits, goals and memory, over MCP.
Governed memory and workspace for any AI: tasks, calendar, mail and pages, with per-action consent.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables interaction with Microsoft Planner tasks through natural language using Azure CLI authentication. Supports listing plans, creating/updating/deleting tasks, managing buckets, and integrating GitHub links without complex OAuth setup.911ISC
- AlicenseAqualityBmaintenanceEnables AI coding agents to read Microsoft Planner and To Do tasks across multiple M365 tenants with proper authentication, and supports optional write operations limited to tasks the agent created.1419 PyPIMIT
- AlicenseAqualityDmaintenanceEnables Claude to manage Microsoft Planner plans, buckets, and tasks via the Microsoft Graph API with OAuth 2.0 authentication.141ISC
- AlicenseAqualityDmaintenanceEnables AI agents to interact with Microsoft Teams through Microsoft Graph API, using delegated device-code authentication to act on behalf of the user.1637 npmMIT