Kairos MCP server

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.

tenant is fine. No redirect URI needed.

1. Entra admin centre → App registrations → New registration. Single

code sign-in needs this. No client secret is used anywhere.

1. Authentication → Settings → enable Allow public client flows. Device

Tasks.ReadWrite ("Create, read, update and delete user's tasks and projects"). Nothing else.

1. API permissions → Microsoft Graph → Delegated → add

is a secret.

1. Copy the Application (client) ID and Directory (tenant) ID. Neither

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 kairoslogin, open the URL, enter the code, then call kairosloginfinish. Either way the token cache lands in ~/.config/kairos/tokencache.json, mode 600, and refreshes silently from then on.

KAIROSDEFAULTPLAN 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

Shortened. The full README is on GitHub.