# Sanban

> Simple kanban that just works. No bloat, no login, no SaaS. JSON-backed boards with a REST API and MCP server. For devs who want tasks tracked without the overhead.

- **Type:** MCP server
- **Install:** `agentstack add mcp-aancw-sanban`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aancw](https://agentstack.voostack.com/s/aancw)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aancw](https://github.com/aancw)
- **Source:** https://github.com/aancw/sanban

## Install

```sh
agentstack add mcp-aancw-sanban
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# sanban

Simple kanban that just works. No bloat, no login, no SaaS.

JSON-backed boards with a REST API, MCP server, and a dark UI. For devs who want tasks tracked without the overhead.

## Screenshots

## Quick Start

```bash
uv sync
uv tool install .
sanban              # http://localhost:8900
```

The web server runs independently. Agents connect via MCP separately.

## Setup with an AI Agent

Paste this into opencode, Claude Code, Cursor, or any AI agent — it will install sanban, start the server, register MCP, load the skill, and verify everything:

```
Clone https://github.com/aancw/sanban, run `uv tool install .` from inside the repo (binary lands at ~/.local/bin/sanban — ensure ~/.local/bin is on PATH, e.g. `export PATH="$HOME/.local/bin:$PATH"`), start the server with `sanban` running in the background (or nohup/disown), register it as an MCP server named "sanban" running `sanban --mcp-only`, copy SKILL.md from the cloned repo into the agent's skills folder (e.g. ~/.claude/skills/sanban/SKILL.md or ~/.agents/skills/sanban/SKILL.md), then call `list_boards` to confirm it works.
```

## Features

- Multiple boards with custom columns
- Drag-and-drop between columns
- Priority, effort, tags, assignees, due dates
- Full-text search and filters
- Markdown in titles and descriptions (code blocks with syntax highlighting)
- Edit and delete buttons on every card
- Keyboard shortcuts (`/` search, `n` new, `e` expand)
- Agent-ready via MCP server

## Why

- **No database** — one JSON file per board in `~/.sanban/boards/`, easy to diff, commit, back up
- **No auth** — local-first, runs on localhost
- **No framework** — vanilla JS frontend, Geist font, dark mode
- **Multi-board** — one server, unlimited boards

## REST API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/boards` | List all boards |
| `POST` | `/api/boards` | Create board `{ name, columns? }` |
| `GET` | `/api/boards/:id` | Get board with items |
| `DELETE` | `/api/boards/:id` | Delete board |
| `GET` | `/api/boards/:id/items` | List items (`?q=`, `?status=`, `?tag=`, `?assignee=`) |
| `POST` | `/api/boards/:id/items` | Create item |
| `PATCH` | `/api/boards/:id/items/:iid` | Update item |
| `DELETE` | `/api/boards/:id/items/:iid` | Delete item |
| `GET` | `/api/search?q=` | Search across boards |

## MCP Server

Agents interact with boards via MCP stdio. This is a separate process from the web server — both read/write the same JSON files.

### Agent Config (opencode.json)

```json
{
  "mcp": {
    "sanban": {
      "type": "local",
      "command": ["sanban", "--mcp-only"],
      "enabled": true
    }
  }
}
```

Or running from source:

```json
{
  "mcp": {
    "sanban": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/sanban", "python", "-m", "sanban.server", "--mcp-only"],
      "enabled": true
    }
  }
}
```

> **Other agents:** Adapt the config format for your CLI agent (Claude Desktop, Cursor, etc.). The command is always `sanban --mcp-only` — only the config wrapper changes.

### Tools

| Tool | Description |
|------|-------------|
| `list_boards` | List all boards |
| `create_board(name, columns?)` | Create a new board |
| `get_board(board_id)` | Get board details + items |
| `create_item(board_id, title, ...)` | Add an item |
| `update_item(board_id, item_id, ...)` | Update fields |
| `move_item(board_id, item_id, new_status)` | Move to column |
| `delete_item(board_id, item_id)` | Remove item |
| `search(query, board_id?)` | Search across boards |

## Run Modes

```bash
sanban                # web server (REST API + UI) — keep this running
sanban --mcp-only     # MCP stdio — for agent config
sanban --rest-only    # REST only, no UI
sanban --port 9000    # custom port
```

**Typical setup:** run `sanban` in a terminal (or background it), then add `sanban --mcp-only` to your agent config. Both use the same `~/.sanban/boards/` data.

## Data

Boards live in `~/.sanban/boards/.json`. Override with `SANBAN_DATA_DIR`.

## For Agents

See [SKILL.md](./SKILL.md) for the full agent reference — API examples, MCP tools, item fields, and keyboard shortcuts.

## Tech

Python 3.10+, FastAPI, uvicorn, MCP SDK. No database, no framework, no build step.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aancw](https://github.com/aancw)
- **Source:** [aancw/sanban](https://github.com/aancw/sanban)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-aancw-sanban
- Seller: https://agentstack.voostack.com/s/aancw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.