---
title: "MCP Server"
description: "Control Kan from Claude Desktop, Codex, and other MCP-compatible AI clients."
tag: "NEW"
---

Kan ships with a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets any MCP-compatible AI client read and control your Kan instance using natural language: list boards, move cards, manage checklists, invite members, and more.

## Two ways to connect

<CardGroup cols={2}>
  <Card title="Hosted" icon="cloud" color="#0284c7">
    Point your client at `https://mcp.kan.bn` with an API key. No install, no
    environment variables. **Requires a Team, Pro, or Enterprise workspace
    plan** on Kan Cloud.
  </Card>
  <Card title="Local" icon="terminal" color="#65a30d">
    Run the server yourself with `npx`. Works against self-hosted or Kan Cloud
    instances, on any plan including Free.
  </Card>
</CardGroup>

## Hosted (Kan Cloud)

<Note>
  The hosted endpoint requires a **Team, Pro, or Enterprise** workspace plan. An
  API key belonging to an account with only Free-plan workspaces gets a `403`
  from every request. Use the Local server below instead: it works on any plan.
</Note>

Get a Kan Cloud API key from **Settings → API Keys → Create key**, then point your client at:

```
https://mcp.kan.bn
```

authenticating with:

```
Authorization: Bearer kan_your_api_key_here
```

For example, in Claude Desktop's config:

```json
{
  "mcpServers": {
    "kan": {
      "type": "http",
      "url": "https://mcp.kan.bn",
      "headers": {
        "Authorization": "Bearer kan_your_api_key_here"
      }
    }
  }
}
```

<Note>
  Exact config syntax for remote/HTTP MCP servers varies by client and changes
  as clients add support. Check your client's docs if the shape above doesn't
  match. Every client needs the same two things: the URL and the `Authorization:
  Bearer` header.
</Note>

## Local (self-hosted or Kan Cloud, any plan)

### Prerequisites

- Node.js 18+
- A running Kan instance (self-hosted or cloud)
- A Kan API key (**Settings → API Keys → Create key**)

### Installation

You do **not** need to clone the repository. The recommended way is `npx`, which runs the server on-demand and always uses the latest version:

```bash
npx -y @kan.bn/mcp
```

Alternatively, install it globally:

```bash
npm install -g @kan.bn/mcp
kan-mcp
```

### Configuration

The server is configured via two environment variables:

| Variable        | Description                         |
| --------------- | ----------------------------------- |
| `KAN_BASE_URL`  | Base URL of your Kan instance       |
| `KAN_API_TOKEN` | API key from your Kan user settings |

`KAN_BASE_URL` is whatever instance you're running the API key against:

<Tabs>
  <Tab title="Kan Cloud">
    ```bash
    KAN_BASE_URL=https://kan.bn
    ```

  </Tab>
  <Tab title="Self-hosted">
    ```bash
    KAN_BASE_URL=https://your-kan-instance.com
    ```

    During local development against a self-hosted instance running on your machine, this is typically:

    ```bash
    KAN_BASE_URL=http://localhost:3000
    ```

  </Tab>
</Tabs>

### Client setup

<Tabs>
  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    ```json
    {
      "mcpServers": {
        "kan": {
          "command": "npx",
          "args": ["-y", "@kan.bn/mcp"],
          "env": {
            "KAN_BASE_URL": "https://your-kan-instance.com",
            "KAN_API_TOKEN": "kan_your_api_key_here"
          }
        }
      }
    }
    ```

  </Tab>
  <Tab title="Codex CLI">
    Add to `~/.codex/config.toml`:

    ```toml
    [mcp_servers.kan]
    command = "npx"
    args = ["-y", "@kan.bn/mcp"]
    env = { "KAN_BASE_URL" = "https://your-kan-instance.com", "KAN_API_TOKEN" = "kan_your_api_key_here" }
    ```

  </Tab>
  <Tab title="Cursor / VS Code Copilot / other">
    Every MCP stdio client follows the same `command` + `args` + `env` pattern shown above. Point it at:

    ```bash
    command: npx
    args: -y @kan.bn/mcp
    env: KAN_BASE_URL, KAN_API_TOKEN
    ```

  </Tab>
</Tabs>

<Note>
  ChatGPT's MCP support is oriented around remote connectors configured via its
  own UI rather than a client-side config file like the ones above. Check
  ChatGPT's own connector docs for how it expects the URL and credentials to be
  supplied.
</Note>

## Example prompts

Once connected, you can ask your AI assistant things like:

**Browsing**

- _"List all my workspaces"_
- _"Show me all boards in the Marketing workspace"_
- _"What cards are in the Backlog list of the Q3 Planning board?"_
- _"Get the full details of card X including comments and checklists"_

**Managing cards**

- _"Create a card called 'Fix login bug' in the To Do list of the Dev board"_
- _"Move the 'API redesign' card to the In Progress list"_
- _"Set a due date of next Friday on the 'Write docs' card"_
- _"Add a comment to the 'Deploy to prod' card saying the deployment is blocked"_
- _"Duplicate the 'Sprint template' card into the new Sprint 4 list"_
- _"Mark the 'Setup CI' checklist item as complete"_

**Organisation**

- _"Add the 'urgent' label to all cards assigned to me in the Backend board"_
- _"Create a 'Release checklist' checklist on the v2.0 card with items: smoke test, update changelog, tag release"_
- _"What tasks are assigned to @alice in the Mechanics Rework board?"_

**Workspace management**

- _"Create a new workspace called 'Client Projects'"_
- _"Invite bob@example.com to the Marketing workspace as a member"_
- _"Create a new board called 'Sprint 5' in the Dev workspace with lists: Backlog, In Progress, Done"_
- _"Search for anything related to 'authentication' across the Dev workspace"_

## Available tools

The MCP server exposes 46 tools across 7 resource types:

| Resource          | Tools                                                               |
| ----------------- | ------------------------------------------------------------------- |
| Workspaces        | list, find by name, get, create, update, delete, search, check slug |
| Boards            | list, find by name, get, get by slug, create, update, delete        |
| Lists             | create, update, delete                                              |
| Cards             | create, get, update, delete, duplicate, get activities              |
| Card interactions | add/update/delete comment, toggle label, toggle member              |
| Checklists        | create, update, delete, create item, update item, delete item       |
| Labels            | get, create, update, delete                                         |
| Members           | invite, remove, update role, manage invite links                    |

## Troubleshooting

<AccordionGroup>
  <Accordion title="The hosted endpoint returns a 403">
    The API key's account doesn't have a Team, Pro, or Enterprise workspace. The
    hosted server (`mcp.kan.bn`) is a paid-plan feature. Either upgrade a
    workspace, or switch to the Local setup above, which works on any plan.
  </Accordion>
  <Accordion title="Every tool call fails with an authentication error">
    Double check `KAN_API_TOKEN` (local) or the `Authorization` header (hosted):
    it must be a key created under **Settings → API Keys**, not your login
    password. For the local server, confirm `KAN_BASE_URL` points at the
    instance the key was created on (a self-hosted key won't work against Kan
    Cloud, and vice versa).
  </Accordion>
  <Accordion title="Calls start failing partway through a long session">
    API keys are rate limited to 100 requests per minute. An AI client looping
    through many tool calls in quick succession (for example, resolving names to
    IDs one board at a time) can hit this. Ask it to slow down, or batch fewer
    operations per prompt.
  </Accordion>
  <Accordion title="The client can't find the kan-mcp command">
    This applies to the Local setup only. Make sure Node.js 18+ is installed and
    on the `PATH` the client uses to spawn subprocesses. GUI apps like Claude
    Desktop don't always inherit your shell's `PATH`. Using the full `npx`
    invocation (rather than a bare `kan-mcp` after a global install) avoids this
    in most cases.
  </Accordion>
</AccordionGroup>