Content
# Kanban MCP
[Baca dalam Bahasa Indonesia](./README_ID.md)
A full-featured Kanban board with integrated [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, allowing AI coding agents to manage projects and tasks programmatically.
## Table of Contents
- [Tech Stack](#tech-stack)
- [Features](#features)
- [Getting Started](#getting-started)
- [MCP Server](#mcp-server)
- [Available Tools](#available-tools)
- [Available Resources](#available-resources)
- [Run MCP Server Standalone](#run-mcp-server-standalone)
- [Configure MCP Client](#configure-mcp-client)
- [Usage Example](#usage-example)
- [Scripts](#scripts)
- [Project Structure](#project-structure)
- [AI Agent Integration](#ai-agent-integration)
- [System Prompt](#system-prompt)
- [Skill (Antigravity)](#skill-antigravity)
- [License](#license)
## Tech Stack
| Layer | Technology |
| ----------- | --------------------------- |
| Framework | Next.js 16 (App Router) |
| Language | TypeScript |
| Database | SQLite + Drizzle ORM |
| UI | shadcn/ui + Tailwind CSS v4 |
| State | Zustand |
| Drag & Drop | @dnd-kit |
| MCP | @modelcontextprotocol/sdk |
## Features
- **Kanban Board** — Drag-and-drop tasks across Backlog, Todo, In Progress, In Review, Done
- **Dashboard** — Summary cards, donut charts (status/priority), 14-day trend bar chart, project breakdown
- **Sub-tasks** — Checklist-style sub-tasks with progress bar
- **Labels** — Custom color labels per project
- **Comments** — Timestamped comment threads on tasks
- **Activity Log** — Full history of task changes
- **Search & Filter** — Real-time search + priority filter on board
- **CSV Export** — Export all tasks or per-project
- **Dark Mode** — Enabled by default
- **MCP Server** — 13 tools + 4 resources for AI agent integration
## Getting Started
### Prerequisites
- Node.js 18+
- npm
### Installation
```bash
git clone https://github.com/dzikrihilman/kanban-mcp.git
cd kanban-mcp
npm install
```
### Database Setup
```bash
npm run db:generate
npm run db:migrate
```
### Run Development Server
```bash
npm run dev
```
Open [http://localhost:3000](http://localhost:3000).
## MCP Server
The MCP server exposes project and task management as tools for AI coding agents (Claude, Cursor, Windsurf, etc).
### Available Tools
| Tool | Description |
| ----------------------- | -------------------------------------- |
| `list_projects` | List all projects with task counts |
| `get_project` | Get project details |
| `create_project` | Create new project |
| `update_project` | Update project fields |
| `delete_project` | Delete project and all tasks |
| `list_tasks` | List tasks (filter by status/priority) |
| `get_task` | Get task with comments |
| `create_task` | Create task with all fields |
| `update_task` | Update task with activity logging |
| `delete_task` | Delete task |
| `move_task` | Move task between columns |
| `add_comment` | Add comment to task |
| `search_tasks` | Search by keyword |
| `get_dashboard_summary` | Full dashboard statistics |
### Available Resources
| URI | Description |
| ----------------------------- | ------------------ |
| `kanban://projects` | All projects |
| `kanban://project/{id}` | Project detail |
| `kanban://project/{id}/tasks` | Project tasks |
| `kanban://task/{id}` | Task with comments |
### Run MCP Server Standalone
```bash
npm run mcp:start
```
### Configure MCP Client
Add the following to your MCP client configuration:
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"kanban-mcp": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/kanban-mcp/src/mcp-server/index.ts"]
}
}
}
```
**Cursor / Windsurf / Antigravity** (`mcp_config.json`):
```json
{
"mcpServers": {
"kanban-mcp": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/kanban-mcp/src/mcp-server/index.ts"]
}
}
}
```
> Replace `/absolute/path/to/kanban-mcp` with the actual path to your project.
### Usage Example
Once configured, your AI agent can:
```
"Create a new project called 'My App' and add 3 tasks to it"
"Move task X to in_progress"
"Show me the dashboard summary"
"Export all tasks as CSV"
```
## Scripts
| Script | Description |
| --------------------- | --------------------------- |
| `npm run dev` | Start Next.js dev server |
| `npm run build` | Production build |
| `npm run start` | Start production server |
| `npm run mcp:start` | Start MCP server (stdio) |
| `npm run db:generate` | Generate Drizzle migrations |
| `npm run db:migrate` | Run database migrations |
## Project Structure
```
src/
├── app/
│ ├── api/ # API routes
│ │ ├── activity/ # Activity log
│ │ ├── analytics/ # Analytics data
│ │ ├── comments/ # Comments CRUD
│ │ ├── dashboard/ # Dashboard summary
│ │ ├── export/ # CSV export
│ │ ├── labels/ # Labels CRUD
│ │ ├── projects/ # Projects CRUD
│ │ ├── task-labels/ # Task-label junction
│ │ └── tasks/ # Tasks CRUD + reorder
│ ├── projects/[id]/ # Kanban board page
│ └── page.tsx # Dashboard page
├── components/
│ ├── charts/ # DonutChart, MiniBarChart
│ ├── dashboard/ # DashboardView
│ ├── kanban/ # Board, Column, Card, FilterBar, etc.
│ ├── layout/ # AppSidebar
│ └── ui/ # shadcn/ui components
├── hooks/
│ └── useKanbanStore.ts # Zustand store
├── lib/db/
│ ├── schema.ts # Drizzle schema
│ ├── index.ts # DB client
│ └── migrate.ts # Migration runner
├── mcp-server/
│ ├── index.ts # MCP server (13 tools, 4 resources)
│ └── db-client.ts # Standalone DB client for MCP
└── types/
└── index.ts # Shared types
```
## AI Agent Integration
To make your AI agent automatically track every development task using Kanban MCP, you can add a system prompt and/or install it as a skill.
### System Prompt
Add the system prompt from [`docs/SYSTEM_PROMPT.md`](./docs/SYSTEM_PROMPT.md) to your AI agent configuration. This instructs the agent to:
- Automatically create tasks before starting any work
- Update task status as work progresses
- Add comments to document technical decisions
- Break complex work into sub-tasks
- Use consistent title formats (`[Feature]`, `[Fix]`, `[Refactor]`, `[Docs]`, `[Test]`)
See the file for setup instructions for Claude Desktop, Cursor, Windsurf, and Antigravity.
### Skill (Antigravity)
Copy [`docs/SKILL.md`](./docs/SKILL.md) to your Antigravity skills folder:
```bash
mkdir -p ~/.gemini/antigravity/skills/kanban-mcp
cp docs/SKILL.md ~/.gemini/antigravity/skills/kanban-mcp/SKILL.md
```
Once installed, the agent will automatically activate the skill when it detects keywords like `task`, `project`, `kanban`, `track`, `progress`, `todo`, or `backlog`.
See [`docs/SKILL.md`](./docs/SKILL.md) for the full workflow reference and rules.
## License
MIT
