KamKan-MCP-SKILL

# kamkan-mcp MCP server for [KamKan](https://github.com/dayeggpi/KamKan) kanban boards. Lets Claude Code, Codex, and Gemini CLI read and write your boards directly. ## Prerequisites - Node.js ≥ 18 (`node -v` to check) - KamKan installed and set up (workspace configured) ## Install ```bash npm install -g kamkan-mcp ``` ## Configure your CLI ### Claude Code Standard install (workspace auto-discovered from `%APPDATA%\KamKan\settings.json`): ```bash claude mcp add --scope user kamkan -- kamkan-mcp ``` Portable/custom install: ```bash claude mcp add --scope user -e KAMKAN_WORKSPACE="C:\BOARDS" kamkan -- kamkan-mcp ``` Verify it loaded: run `/mcp` inside Claude Code — `kamkan` should appear green. --- ### Codex Add to `~/.codex/config.toml`: **Standard:** ```toml [mcp_servers.kamkan] command = "kamkan-mcp" ``` **Portable:** ```toml [mcp_servers.kamkan] command = "kamkan-mcp" [mcp_servers.kamkan.env] KAMKAN_WORKSPACE = "C:\\path\\to\\your\\workspace" ``` --- ### Gemini CLI Add to `~/.gemini/settings.json` (create the file if it doesn't exist): **Standard:** ```json { "mcpServers": { "kamkan": { "command": "kamkan-mcp" } } } ``` **Portable:** ```json { "mcpServers": { "kamkan": { "command": "kamkan-mcp", "env": { "KAMKAN_WORKSPACE": "C:\\path\\to\\your\\workspace" } } } } ``` --- ## Standard vs portable | Setup | How workspace is found | |---|---| | Standard (default KamKan install) | Auto-discovered from `%APPDATA%\KamKan\settings.json` — no env var needed | | Portable / custom `settingsLocation` | Set `KAMKAN_WORKSPACE` to the folder containing your `settings.json` | `KAMKAN_WORKSPACE` always wins if set. --- ## Available tools | Tool | What it does | |---|---| | `list_boards` | List all board IDs in the workspace | | `get_board` | Get a board's columns and tasks | | `create_board` | Create a new board (custom columns optional) | | `create_task` | Add a task to a column | | `update_task_title` | Rename a task | | `move_task` | Move a task to a different column | | `complete_task` | Mark a task done or not done | | `delete_task` | Delete a task | | `get_task_detail` | Read tags, priority, due date, description, subtasks | | `set_task_detail` | Write/update task detail (partial updates safe) | ## Usage examples Once configured, talk to your agent naturally: ``` List my boards Show tasks on board ==TODO Add "fix login bug" to the Ongoing column on ==TODO Move task 42 on ==TODO to Done Create a board called WORK with columns Inbox, Doing, Review, Done Set priority high and due date 2026-06-01 on task 7 of board CLEAN ``` ## Task tracking skill The repo includes skills that tell the AI to automatically plan and track its own work on a KamKan board — breaking requests into tasks, moving them through Todo → Doing → Done as it works. ### Install the skill **Claude Code** — copy to your user skills directory: ```bash # macOS / Linux cp skills/claude/kamkan.md ~/.claude/skills/kamkan.md # Windows copy skills\claude\kamkan.md %USERPROFILE%\.claude\skills\kamkan.md ``` **Codex** — copy to your user skills directory: ```bash # macOS / Linux mkdir -p ~/.codex/skills/kamkan cp skills/codex/kamkan/SKILL.md ~/.codex/skills/kamkan/SKILL.md # Windows mkdir %USERPROFILE%\.codex\skills\kamkan copy skills\codex\kamkan\SKILL.md %USERPROFILE%\.codex\skills\kamkan\SKILL.md ``` **Gemini CLI** — copy to your user skills directory: ```bash # macOS / Linux mkdir -p ~/.gemini/skills cp skills/gemini/kamkan.md ~/.gemini/skills/kamkan.md # Windows mkdir %USERPROFILE%\.gemini\skills copy skills\gemini\kamkan.md %USERPROFILE%\.gemini\skills\kamkan.md ``` ### Use it **Claude Code** — invoke at the start of a session: ``` /kamkan MY_BOARD ``` Or set a default board so it activates automatically: ```bash claude mcp add --scope user -e KAMKAN_WORKSPACE="..." -e KAMKAN_TASK_BOARD="MY_BOARD" kamkan -- kamkan-mcp ``` **Codex** — same: type `/kamkan MY_BOARD` or set `KAMKAN_TASK_BOARD` in your env block in `config.toml`. **Gemini CLI** — same: type `/kamkan MY_BOARD` or set `KAMKAN_TASK_BOARD` in the `env` block in `~/.gemini/settings.json`. Once active, the AI will: 1. Break your request into discrete tasks and add them to the board 2. Move each task to Doing when it starts, Done when it finishes 3. Add newly discovered tasks to the board as they appear 4. Report a summary at the end of the session --- ## Workspace not found? If the server can't find your workspace, set the env var explicitly: ```bash # find your workspace path in KamKan → Settings → Workspace export KAMKAN_WORKSPACE="/path/to/your/workspace" ``` Then add it to your CLI config as shown in the Portable sections above.