{
  "mcpServers": {
    "kanban": {
      "type": "stdio",
      "command": "npx",
      "args": ["kanban-lite", "mcp"],
      "env": { "KANBAN_DIR": "/path/to/your/project/.kanban" }
    }
  }
}

MCP Server

The MCP server is the agent-native interface for Kanban Lite. It runs over stdio, delegates its built-in operations to the same KanbanSDK methods used by the CLI and standalone server, and can be extended by active plugin packages.

Starting the server

kl mcp
kl mcp --dir .kanban
kanban-mcp --dir .kanban
npx kanban-lite mcp

The current implementation exposes stdio transport only.

When the server starts, it resolves the workspace in this order:

1. --dir <path>
2. KANBAN_DIR
3. KANBAN_FEATURES_DIR (legacy alias)
4. optional --config <path> during auto-detection
5. auto-detect from the current working directory

If your MCP client does not inherit your shell environment, pass the directory and token explicitly in the client config:

{
  "mcpServers": {
    "kanban": {
      "type": "stdio",
      "command": "kl",
      "args": ["mcp", "--dir", "/absolute/path/to/project/.kanban"],
      "env": {
        "KANBAN_LITE_TOKEN": "kl-your-token"
      }
    }
  }
}

Authentication and environment

The MCP server itself does not prompt for credentials. It reads auth state from the process environment and the workspace configuration:

• KANBAN_LITE_TOKEN is the preferred token environment variable.
• KANBAN_TOKEN is still accepted as a compatibility alias.
• If no auth providers are configured for the workspace, MCP access remains open just like the CLI and SDK.
• If auth is enabled, pass the token through your MCP client config or launch the server from a shell that already exports it.

Useful diagnostics:

• get_auth_status — shows active auth providers plus safe token-source metadata
• get_workspace_info — includes auth, storage, workspace root, and kanban directory details

For the full auth model and the local / rbac provider details, see docs/auth.md.

Tool conventions

A few conventions make the MCP surface easier to work with:

• Tool names use snake_case.
• Inputs are mostly camelCase, with one notable exception: trigger_action expects card_id.
• Most tools return pretty-printed JSON inside a text content block. Some mutation tools return a short success string instead.
• Errors are returned as MCP tool errors (isError: true). Auth and plugin-setting failures may return structured JSON payloads instead of plain text.
• Board/listing tools still accept boardId when board scope matters. Card-focused tools resolve the owning board from cardId automatically and no longer require a boardId input.
• Most card-focused tools support partial card ID matching. If zero cards or multiple cards match, the tool returns an error and asks for a more specific ID.
• delete_card is a soft delete that moves the card to the deleted column. Use permanent_delete_card for irreversible deletion.
• add_attachment requires an absolute host file path that is readable by the machine running the MCP server.
• Built-in and plugin-owned mutations run through the same SDK event/auth pipeline as the CLI and REST API, so webhooks, callbacks, auth checks, and storage providers behave consistently across interfaces.

Search and filtering

list_cards is the main discovery tool. It returns a summary list (id, rendered title, status, priority, assignee, labels, dueDate) rather than the full card body. Use get_card when you want the full record.

Search behavior matches the CLI and REST API:

• searchQuery — free-text search across card content and metadata values
• inline metadata tokens inside searchQuery such as meta.team: backend
• fuzzy: true — typo-tolerant matching across text and metadata values
• metaFilter — structured field filtering using dot-notation keys like {"links.jira":"PROJ-123"}
• sort — one of created:asc, created:desc, modified:asc, or modified:desc

Example input for list_cards:

{
  "boardId": "default",
  "searchQuery": "release meta.team: backnd",
  "fuzzy": true,
  "metaFilter": {
    "links.jira": "PROJ-123"
  },
  "sort": "modified:desc"
}

Built-in tools

The core MCP server currently registers the following built-in tools. Active plugins may add more.

Boards and board actions

Cards, forms, and actor-scoped card state

get_active_card and the card.state tools are related but not identical:

• get_active_card reflects workspace/UI-style active-card selection
• get_card_state, open_card, and read_card work with actor-scoped unread/open state managed by the shared card-state backend

Attachments, comments, and logs

Columns, labels, and display settings

Workspace diagnostics, plugin settings, and storage

A few plugin-settings guardrails are worth calling out:

• install_plugin_settings_package only accepts exact unscoped kl-* package names
• install scope must be either workspace or global
• returned option payloads are redacted for secret safety

Plugin-contributed MCP tools

The built-in tool list above is not the whole story. Active plugins can contribute additional MCP tools through the narrow mcpPlugin.registerTools(ctx) seam.

Current first-party example:

• kl-plugin-webhook adds:
  • list_webhooks
  • add_webhook
  • update_webhook
  • remove_webhook

A few important notes:

• Plugin packages must be installed in the same runtime environment that launches the MCP server.
  • If you run kl mcp from a project-local install, install plugins in that workspace.
  • If you run a global binary, install plugins globally or otherwise make them resolvable from that runtime.
• Plugin-contributed tools receive the same SDK instance, auth wrapper, workspace paths, and error-helper behavior as built-in tools.
• Duplicate MCP tool names are rejected during server startup.

For the broader plugin model, see docs/plugins.md. For webhook-specific behavior, see docs/webhooks.md.

Common call patterns

Create a form-aware card

Tool: create_card

{
  "boardId": "default",
  "title": "Investigate outage",
  "body": "Collect incident details and assign an owner.",
  "status": "todo",
  "priority": "high",
  "tasks": ["Draft incident summary", "- [x] Page on-call"],
  "actions": ["retry", "notify"],
  "forms": [
    { "name": "incident-report" }
  ],
  "formData": {
    "incident-report": {
      "service": "billing"
    }
  }
}

Submit a card form

Tool: submit_card_form

{
  "cardId": "investigate-outage",
  "formId": "incident-report",
  "data": {
    "severity": "critical",
    "owner": "alice"
  }
}

Acknowledge unread activity without changing open-card state

Tool: read_card

{
  "cardId": "investigate-outage"
}

Configure a plugin provider

Tool: select_plugin_settings_provider

{
  "capability": "auth.identity",
  "providerId": "local"
}

Tool: update_plugin_settings_options

{
  "capability": "auth.identity",
  "providerId": "local",
  "options": {
    "users": [
      {
        "username": "alice",
        "password": "••••••",
        "role": "admin"
      }
    ]
  }
}

Troubleshooting

• Tool says a card was not found or matched multiple cards — pass a more specific cardId (the full card ID if needed). Card-focused tools now resolve board scope from the card itself.
• Auth-denied errors — confirm the client passes KANBAN_LITE_TOKEN (or KANBAN_TOKEN) into the MCP process and inspect get_auth_status.
• A plugin tool is missing — install the plugin package in the same runtime environment as the MCP server and verify the workspace/plugin configuration selects it.
• add_attachment fails — use an absolute path on the host machine that is readable from the MCP process.
• You expected a hard delete — delete_card only soft-deletes; use permanent_delete_card to remove the card entirely.
• Your token is in .env but MCP still cannot see it — MCP clients do not automatically load workspace .env files unless the launch command or wrapper shell exports them first.

Related docs

• README.md — quick-start and cross-interface overview
• docs/auth.md — auth providers, token handling, and diagnostics
• docs/forms.md — shared form model used by create_card, update_card, and submit_card_form
• docs/plugins.md — plugin discovery, provider selection, and MCP registration seam
• docs/webhooks.md — webhook delivery and plugin-owned webhook MCP tools
• docs/sdk.md — underlying SDK methods that the MCP server delegates to