kaiten-mcp

English · Русский

MCP server for full control over Kaiten from any MCP client. Provides 36 kaiten_* tools: spaces, boards, cards, comments, checklists, time tracking, tags, members, flexible queries and day planning.

Two ways to use it

(a) Local stdio server via npm

Installed as an npm package and launched locally by an MCP client. The token is kept in environment variables or requested interactively (elicitation).

Good for: Cowork, Claude Code, Claude Desktop (local).

(b) Remote server on Vercel

The Next.js app in apps/web is deployed to Vercel and becomes a remote MCP server with OAuth 2.1 + PKCE. Each teammate connects by URL in Claude Desktop and enters their own Kaiten API token — no handing tokens around through configs.

Good for: team usage, Claude Desktop (remote connector).

Related MCP server: kaiten-mcp-server

Local stdio server

Features

36 kaiten_* tools:

Planning tools

• kaiten_today_tasks — the user's active cards due today or earlier, sorted by priority and due date.

• kaiten_overdue_cards — overdue cards only.

• kaiten_plan_day — a ready-made day plan: grouped into "Overdue / Today" plus markdown text and a structured list.

If user_id is omitted, the token's current user is used.

Requirements

• Node.js >= 20 (22 LTS recommended, pinned in mise.toml).

• A personal Kaiten API token.

Installation

# From npm:
npm install -g kaiten-mcp

# Or run on demand without installing:
npx kaiten-mcp

# From source:
git clone https://github.com/aimuzov/kaiten-mcp.git
cd kaiten-mcp
npm install
npm run build

Configuration

Copy packages/cli/.env.example to packages/cli/.env and fill it in (or pass the variables through your MCP client config):

Where to get a token: in Kaiten, open your profile → the API keys section and create a token.

Interactive token request (elicitation)

* — KAITEN_API_URL and KAITEN_API_TOKEN are not required at startup. If they are not set, the server will ask you for them right inside the client on the first call to Kaiten — via the standard MCP elicitation mechanism. The entered values are kept only in process memory for the duration of the session and are never written to disk.

• Works only if the client supports elicitation (declares the elicitation capability).

• If the client does not support elicitation and the variables are unset, any tool call returns a clear error asking you to set the variables.

• Want to always enter the token manually? Just leave KAITEN_API_TOKEN unset.

Connecting in Cowork

{
  "mcpServers": {
    "kaiten": {
      "command": "kaiten-mcp",
      "env": {
        "KAITEN_API_URL": "https://your-domain.kaiten.ru/api/latest",
        "KAITEN_API_TOKEN": "your-token"
      }
    }
  }
}

The env block is optional — without it the server will ask for the token right inside Cowork on the first Kaiten call (see Interactive token request).

Connecting in Claude Code

claude mcp add kaiten \
  --env KAITEN_API_URL=https://your-domain.kaiten.ru/api/latest \
  --env KAITEN_API_TOKEN=your-token \
  -- kaiten-mcp

Connecting in Claude Desktop (local)

In claude_desktop_config.json add the same mcpServers block as for Cowork above.

Tests (stdio)

npm run build
npm run smoke -w kaiten-mcp        # initialize + tools/list (no credentials)
npm run test:elicit -w kaiten-mcp  # interactive token request check
npm run test -w @kaiten-mcp/core   # core unit tests (vitest)

Remote server on Vercel

The apps/web app is a Next.js server with a full OAuth 2.1 + PKCE flow that deploys to Vercel. Teammates connect it in Claude Desktop by URL rather than through configs with tokens.

Important: Claude Desktop supports only OAuth authentication for remote connectors — you cannot pass a token via a header or URL parameter. That is why a full OAuth flow is implemented here.

How it works

1. An administrator deploys apps/web to Vercel.

2. A teammate in Claude Desktop: Settings → Connectors → Add custom connector → enters the deployment URL.

3. Claude Desktop starts OAuth: the browser opens, a form is shown — the teammate enters their personal Kaiten API token.

4. The token is encrypted via JWE (AUTH_SECRET) and returned to Claude Desktop as a Bearer token.

5. On every MCP request the server decrypts the token and talks to Kaiten on behalf of that specific teammate.

6. No database is needed — the architecture is fully stateless.

Environment variables

Copy apps/web/.env.example to apps/web/.env.local and fill it in for local development.

Deploy to Vercel

Recommended — Root Directory in the dashboard:

1. Import the repository into Vercel.

2. In project settings set Root Directory = apps/web.

3. Vercel auto-detects Next.js and configures everything.

4. In Environment Variables add AUTH_SECRET (required) and optionally KAITEN_API_URL.

Alternative — vercel.json in the root:

The repository root already contains a vercel.json that tells Vercel to build apps/web from the monorepo root. Just import the repository without changing the Root Directory.

Connecting a teammate in Claude Desktop

Settings → Connectors → Add custom connector → enter the deployment URL (e.g. https://kaiten-mcp.vercel.app). Claude Desktop starts the OAuth flow: a form opens where the teammate enters their Kaiten API token. After that all kaiten_* tools become available.

Monorepo architecture

kaiten-mcp/
├── package.json                      # npm workspaces
├── packages/
│   ├── core/  (@kaiten-mcp/core)     # Shared core: Kaiten client, 36 tools,
│   │                                 # JWE tokens, PKCE verification, types
│   └── cli/   (kaiten-mcp)           # stdio MCP server (npm package, bin)
└── apps/
    └── web/   (@kaiten-mcp/web)      # Next.js remote server on Vercel,
                                      # OAuth 2.1 + PKCE + MCP endpoint

Packages

• @kaiten-mcp/core — shared logic: Kaiten API client, all 36 tools, JWE seal/open (for OAuth tokens), PKCE S256 verification, entity types. Tests: vitest.

• kaiten-mcp (packages/cli) — the published npm package, a stdin/stdout MCP server. Uses @kaiten-mcp/core. Tests: smoke + elicitation.

• @kaiten-mcp/web (apps/web) — Next.js app: OAuth 2.1 (PKCE + DCR), MCP endpoint via mcp-handler. Test: npm run test:flow.

Kaiten API notes

• Base path is /api/latest, authentication is Authorization: Bearer <token>.

• Column type: 1 — queue, 2 — in progress, 3 — done.

• Card condition: 1 — active, 2 — archived.

• In search_cards, rare Kaiten parameters can be passed via extra_params.

License

MIT