# AL's Kanban MCP server

An [MCP](https://modelcontextprotocol.io) server that lets Claude Code (or any MCP client) work with boards in an [AL's Kanban](https://kanban.tawalbeh.tech) instance — list boards, create and edit cards, and attach local files.

It talks to your instance over its HTTP API using a personal API token. No database access, no credentials beyond the token.

## Why it runs locally

The server runs as a local stdio process rather than a hosted endpoint, specifically so that `attach_file` works. A remote server cannot reach your filesystem, which would mean passing file contents through the model as base64 — a 5 MB PDF is roughly 1.7M tokens. Running locally, the server reads the file itself and uploads the bytes straight to your instance. They never enter the conversation.

## Setup

**1. Generate a token.** Sign in to your instance, go to `/profile`, and use the **API token** section. The token is shown once — copy it then.

The token acts as you, across every workspace you belong to. Treat it like a password, and revoke it from the same page if it leaks.

**2. Install.**

```bash
git clone https://github.com/alaatawalbeh/Alskanban-MCP.git && cd Alskanban-MCP && npm install
```

**3. Register with Claude Code.** Quote the path if it contains spaces.

```bash
claude mcp add alkanban --scope user --env ALKANBAN_URL=https://kanban.example.com --env ALKANBAN_TOKEN=alk_your_token_here -- node /absolute/path/to/Alskanban-MCP/server.mjs
```

Check it connected:

```bash
claude mcp list
```

## Configuration

| Variable | Required | Default | Meaning |
|---|---|---|---|
| `ALKANBAN_TOKEN` | yes | — | Personal API token from `<instance>/profile` |
| `ALKANBAN_URL` | no | `http://localhost:3000` | Base URL of your instance |

The server exits with status 1 and a message on stderr if `ALKANBAN_TOKEN` is unset.

## Tools

| Tool | Arguments | Does |
|---|---|---|
| `list_workspaces` | — | Workspaces you belong to |
| `list_boards` | `workspaceId` | Boards in a workspace |
| `get_board` | `boardId` | Board with its lists and cards |
| `create_card` | `listId`, `title` | Append a card to a list |
| `update_card` | `cardId`, `title?`, `description?` | Edit title / Markdown description |
| `set_due_date` | `cardId`, `dueAt` | ISO 8601 timestamp, or `null` to clear |
| `move_card` | `cardId`, `toListId`, `beforeCardId?` | Move between lists |
| `attach_file` | `cardId`, `path` | Upload a local file |

Ids flow downward: `list_workspaces` → `list_boards` → `get_board` gives you the `listId` and `cardId` values the write tools need.

## Requirements

- Node.js 20 or newer (uses the built-in `fetch`, `FormData`, and `File`)
- An AL's Kanban instance exposing `/api/v1` and `/api/upload`

## Notes

- Cards created here appear on the next load of the board page; an already-open browser tab will not update on its own.
- `attach_file` is limited to 100 MB, and your instance applies its own smaller per-plan limit on top.
- Attachment responses omit the presigned download URL — it is a short-lived credential with no use inside a conversation. Use the board UI to download.

## License

MIT