Kanban AI

Kanban AI

Open-source AI kanban for side projects. Plan with AI, manage a board in the browser, and (optionally) drive the same board from Cursor or Claude via MCP.

Try the hosted app: kanbanai.dev · Docs: kanbanai.dev/docs · Release updates: kanbanai.dev/docs/release-updates

Most people cloning this repo want the local app. That path is first below.

---

Run locally (recommended)

No Supabase account, no sign-in. One SQLite database under .local/ (gitignored). Vite serves the UI; a small local API on port 3000 handles data and OpenAI.

Requirements: Node.js 18+, npm, and an OpenAI API key for AI features.

git clone https://github.com/orholam/kanban_ai.git
cd kanban_ai/frontend
npm install
cp env.local.example .env.local

Edit .env.local:

VITE_LOCAL_MODE=true
OPENAI_API_KEY=sk-...

Do not prefix the OpenAI key with VITE_ — that would expose it in the browser.

npm run dev:local

Open http://localhost:5173.

What works in local mode

Feature	Local
Kanban board, sprints, tasks, comments	Yes
AI project builder (chat + live workspace) + board assistant	Yes (needs OPENAI_API_KEY)
Project members (invite by email)	Yes — invite collaborator@dev.invalid to try (seeded)
Cloud auth / account / hosted analytics / feedback	No (needs Supabase)
Remote MCP (/api/mcp)	No — use a hosted deploy or vercel dev with Supabase

First run applies frontend/scripts/local-schema.sql. Vite proxies /api to the local process (frontend/vite.config.ts).

Useful scripts

Command	What it does
npm run dev:local	Local SQLite API + Vite (default for contributors)
npm start	Vite only (pair with Supabase / vercel dev)
npm run build	Production build + static SEO prerender (unique HTML per public route; skip with SKIP_PRERENDER=1)
npm run build:no-prerender	Faster local production build

---

Optional: Supabase (cloud auth + sync)

Use this when you want real accounts, multi-device sync, or the hosted MCP server.

1. In frontend/.env.local, set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY, and remove VITE_LOCAL_MODE (or set it to anything other than true).
2. Keep OPENAI_API_KEY for /api/openai.
3. From frontend/, run two terminals: npx vercel dev --listen 3000 then npm start. UI: http://localhost:5173.

Deploy on Vercel

Set OPENAI_API_KEY (and Supabase / MCP vars below) in the Vercel project. The OpenAI key is read only on the server — never put it in VITE_* client env.

frontend/vercel.json pins "buildCommand": "npm run build". Leave it there: Vercel's Vite preset otherwise runs bare vite build and silently skips the SEO prerender, which makes every public URL serve the homepage shell and canonical. See frontend/SEO_SETUP.md. AdSense recovery work (crawlable copy, ads off docs) is logged in docs/adsense-approval-log.md.

---

Ads

Ads are served by TinyAdz/Apitiny via the script tag at the bottom of frontend/index.html (site id + data-test-mode). Two things are easy to break:

• Ad placements. TinyAdz auto-places inline ads by matching CSS class chains it scraped from the landing page, so any other page gets no inventory. Add <AdSlot /> (frontend/src/components/AdSlot.tsx) where an ad belongs — it renders a ta-ad-container div that TinyAdz fills. Currently used on blog posts and both landing variants (not on docs — see docs/adsense-approval-log.md).
• The visitor-engagement gate. TinyAdz renders nothing until it sees a window scroll, mousemove, or touchmove. Because every route scrolls inside a nested overflow-y-auto element, window never emits scroll on its own, so frontend/src/lib/nestedScrollBridge.ts re-broadcasts nested scrolls onto the window from main.tsx. Without it, visitors who only wheel-scroll see zero ads and register zero views.

To preview demo ads locally, set data-test-mode="true" in frontend/index.html.

---

MCP (Cursor, Claude, other agents)

On a hosted deployment, Kanban AI exposes a remote MCP server at /api/mcp with the same board operations as the web app.

• End users: sign in → Connect AI (/connect) → copy the generated config into Cursor or Claude Desktop. Config uses a long-lived personal MCP key (kai_…) so you do not need to reconnect hourly.
• Operators: before Connect AI can issue kai_… keys in production, apply supabase/migrations/20260714120000_mcp_api_keys.sql on the Kanban Supabase project (mruhzlixrwsgwqaodviy). Run ./scripts/apply-mcp-api-keys-migration.sh for the SQL editor link, or supabase db push after linking that project.
• Operators: see docs/MCP_REGISTRY.md and the env table below.
• Discovery: /.well-known/mcp-server · OpenAPI: /openapi/mcp.json · AI index: /llms.txt

Variable	Purpose
SUPABASE_URL	Same as VITE_SUPABASE_URL
SUPABASE_ANON_KEY	Same as VITE_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY	MCP analytics, member invites, personal MCP keys
MCP_API_SECRET	Shared secret for X-MCP-API-Key (also used to encrypt personal keys at rest)
MCP_KEY_ENCRYPTION_SECRET	Optional dedicated secret for encrypting personal MCP keys (falls back to MCP_API_SECRET / service role)
OPENAI_API_KEY	In-app AI (optional for MCP CRUD tools)

Tools: list_projects, get_board, create_project, update_project, delete_project, create_task, update_task, delete_task, list_task_comments, add_task_comment, delete_task_comment.

---

Features

• AI project breakdown and sprint-aware task generation
• Drag-and-drop kanban with priorities, types, due dates, and comments
• Mobile-first board: status tabs + single scroll list, in-flow quick-add, drawer nav, overlay AI assistant
• In-board AI assistant (and @kanban replies on task threads)
• Project members (cloud) or local seeded collaborator for sharing tests
• Dark / light mode
• Optional remote MCP so coding agents manage the same board

Tech stack

React 18, TypeScript, Vite, Tailwind CSS · Local: SQLite API · Hosted: Supabase + Vercel · AI: OpenAI · MCP: mcp-handler

Project layout

frontend/
├── api/                 # Vercel serverless (OpenAI, MCP, feedback, invites)
├── scripts/             # Local schema, prerender, etc.
├── src/
│   ├── components/
│   ├── pages/
│   ├── lib/
│   └── ...
├── public/              # Static assets, llms.txt, OpenAPI, .well-known
└── package.json

Contributing

1. Fork and clone
2. Use Run locally above
3. Branch, commit, open a PR

Issues and ideas: GitHub Issues

License

MIT — see LICENSE.