canban-mcp
Use canban-mcp to inspect and modify Canban boards over Nostr via MCP tools.
Check the agent’s npub, relay status, and company memberships (
whoami).List visible projects, lane/task counts, and editability (
list_projects).Read a project’s ordered lanes and tasks (
get_board) and full task details/body (get_task).Create tasks in a lane with title, markdown body, labels, and assignee.
Update tasks’ title, body, labels, or assignee; unassign with an empty assignee.
Move tasks between lanes or reorder at top/bottom.
Delete tasks for everyone.
Create and rename lanes.
List people and roles for task assignment.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@canban-mcp list the tasks on my canban board"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
canban-mcp
An MCP server that lets AI agents read and work Canban boards. Canban is a kanban board for small teams whose data lives on a Nostr relay. This server runs on the user's own machine, signs with its own Nostr key, and talks straight to the relay. There is no Canban server, no account and no API token.
For AI agents: install and set up canban-mcp for your user
Follow these steps in order. Each one says what to run, what you should see, and what to do if you don't. Run the commands yourself where you can; only step 5 needs the user.
1. Check Node.js
node --versionYou need v22 or later. If node is missing or older, stop and tell the user:
"canban-mcp needs Node.js 22 or later. Install it from https://nodejs.org, then ask me again."
2. Download the server
macOS and Linux:
git clone --depth 1 https://github.com/Punk-Science-Studios-Inc/canban-mcp.git "$HOME/.local/share/canban-mcp" \
|| git -C "$HOME/.local/share/canban-mcp" pull --ff-onlyWindows (PowerShell):
git clone --depth 1 https://github.com/Punk-Science-Studios-Inc/canban-mcp.git "$env:LOCALAPPDATA\canban-mcp"There is nothing to build or install: dist/canban-mcp.mjs is a single self-contained file. The
rest of this guide calls its absolute path SERVER, for example
/home/alex/.local/share/canban-mcp/dist/canban-mcp.mjs. Expand $HOME or %LOCALAPPDATA%
yourself; MCP config files do not.
If git is missing, tell the user to install it and stop.
3. Pick a key file for this agent
Each agent gets its own Nostr key, so its changes on the board are labelled as its own and the user can remove it on its own. Choose a file name that names your client:
You are | Key file |
Claude Code |
|
Claude Desktop |
|
Cursor |
|
Codex |
|
Anything else |
|
On Windows use %APPDATA%\canban\<name>.nsec. Use the absolute path everywhere below; the
rest of this guide calls it KEY_FILE.
4. Create the key and get its npub
macOS and Linux:
CANBAN_KEY_FILE="KEY_FILE" node "SERVER" --whoamiWindows (PowerShell):
$env:CANBAN_KEY_FILE = "KEY_FILE"; node "SERVER" --whoamiExpected output: one line starting with npub1, plus, the first time, a note that a new key was
saved. The key file is created readable only by the user. Never print, copy or send the
contents of the key file. The npub is public and safe to show.
5. Ask the user to let the agent in
Give the user this message, with the real npub and your name filled in:
To let me work on your Canban boards:
Open https://punkscience.ca/canban and sign in.
Go to People (bottom left) and add
npub1…with the name "<your name, e.g. Claude Code>".Open each project I should work on, click Settings, and tick "".
Tell me when that's done. If you aren't an admin of the company, ask an admin to do it. If the person who added me isn't the company owner, the owner needs to open Canban once before I can connect.
Carry on with the next step while you wait; the last step checks whether access has been granted.
6. Register the server with your client
Replace SERVER and KEY_FILE with the absolute paths from steps 2 and 3.
Claude Code (run it; --scope user makes it work in every project):
claude mcp add canban --scope user -e CANBAN_KEY_FILE="KEY_FILE" -- node "SERVER"Claude Desktop: add this to claude_desktop_config.json, merging with any existing
mcpServers, then tell the user to restart Claude Desktop. The file is at
~/Library/Application Support/Claude/claude_desktop_config.json on macOS and
%APPDATA%\Claude\claude_desktop_config.json on Windows.
Cursor: the same JSON goes in ~/.cursor/mcp.json.
{
"mcpServers": {
"canban": {
"command": "node",
"args": ["SERVER"],
"env": { "CANBAN_KEY_FILE": "KEY_FILE" }
}
}
}Codex: add this to ~/.codex/config.toml:
[mcp_servers.canban]
command = "node"
args = ["SERVER"]
env = { CANBAN_KEY_FILE = "KEY_FILE" }Any other MCP client: register a stdio server with command node, argument SERVER,
and environment variable CANBAN_KEY_FILE. If you don't know where your client keeps its MCP
config, ask the user rather than guessing.
Most clients only load new MCP servers at the start of a session. If the canban tools don't
appear, tell the user to restart the client or start a new session.
7. Verify
Call the whoami tool.
Result | Meaning | Do this |
| Working | Call |
| Not let in yet | Repeat the step 5 message. If the user says it's done, ask them to have the company owner open Canban, then call |
A company but no projects | In the company, not on a project | Ask the user to tick you in the project's Settings |
| Can't reach the relay | Tell the user |
Setup is complete when list_projects returns at least one project with "canEdit": true.
Updating
git -C "$HOME/.local/share/canban-mcp" pull --ff-onlyThen restart the client. The key file is untouched, so the agent keeps its identity.
Related MCP server: sanban
Using the tools
Every task has a number within its project (#0, #1, …), starting at 0. Tasks can be given by
number ("#12"), id or exact title; projects, lanes and people by id or exact name (case doesn't
matter). If two projects both have a #12, use the task's id.
"me" as an assignee means the agent. Changes appear live to everyone watching the board.
Tool | Does |
| The agent's npub, relay status, and companies; explains how to get access |
| Projects the agent can see, lane counts, and whether it can edit them |
| A project's lanes and tasks, in order (no task bodies) |
| One task in full, including its markdown body |
| Add a task to a lane (defaults to the first lane), with optional body, labels, assignee and |
| Change title, body, labels, assignee or |
| Move a task to a lane, at the top or bottom |
| Remove a task for everyone |
| Add a lane at the end, or rename one |
| Move a lane to a position, 1 being leftmost |
| People in a company and their roles, for assigning |
Organizations without a subscription are on the free plan (1 project, 3 people); whoami shows each company's plan, and changes that would go past the free plan, or any change in an organization already over it, are refused with the reason.
Tasks can depend on other tasks in the same project. get_board and get_task show dependsOn and waitingOn (dependencies not yet in the last lane); work tasks with no waitingOn first.
Good habits: call get_board before changing a board you haven't seen this session, prefer
move_task over editing a task's lane by hand, and confirm with the user before delete_task.
Configuration
Variable | Default | Purpose |
|
| The agent's key; created on first run |
| none | Use this nsec instead of a key file |
|
| Relay to connect to |
Security
The key file holds the agent's secret key, created with permissions
600. Anyone with it can act as the agent, so don't commit, share or paste it.The agent can only write to projects it is ticked on. Removing it on the People page cuts it off at once.
Board content is not encrypted. Any member of the relay could read it with a raw Nostr client.
Develop
npm ci
npm test # tools against an in-process relay that enforces NIP-42 login
npm run build # rebuilds dist/canban-mcp.mjs, which is committedsrc/domain/ is copied from the Canban web app, which owns the data model. After changing it
there, run npm run sync-domain (it expects ../canban), then test, build and commit dist/.
CI fails if the committed bundle doesn't match the source.
Licence
MIT. See LICENSE.
Available Tools
11 toolscreate_laneCreate laneB
Add a lane to the right-hand end of a project.
Inputs: name (required), project (required).
create_taskCreate taskA
Add a task to the bottom of a lane. Defaults to the first lane.
Inputs: title (required), project (required), body, lane, +2 more.
delete_taskDelete taskBDestructive
Remove a task from the board for everyone.
Inputs: task (required).
get_boardGet boardARead-only
Every lane of a project in order, with its tasks in order. Bodies are omitted; use get_task for one.
Inputs: project (required).
get_taskGet taskBRead-only
One task in full, including its markdown body and lane.
Inputs: task (required).
list_peopleList peopleARead-only
People in a company, with their roles. Use their names as task assignees.
Inputs: company.
list_projectsList projectsARead-only
Projects this agent can see, with lane and task counts.
Inputs: no named parameters.
move_taskMove taskB
Move a task to another lane (or reorder within one), at the top or bottom.
Inputs: lane (required), task (required), position.
rename_laneRename laneC
Rename a lane in a project.
Inputs: lane (required), name (required), project (required).
update_taskUpdate taskA
Change a task's title, body, labels or assignee. Fields left out stay as they are. Pass assignee "" to unassign.
Inputs: task (required), body, title, labels, +1 more.
whoamiWho am IARead-only
This agent's Nostr identity, relay status and the companies it belongs to. Explains how to grant access if it has none.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool maps to a distinct resource+action (identity, projects, board, task CRUD, lane create/rename, people), and get_board vs get_task is explicitly clarified by the note that bodies are omitted. Minor residual overlap between get_board and get_task is the only soft spot.
Consistent verb_noun snake_case throughout (list_projects, get_task, create_task, update_task, move_task, delete_task, create_lane, rename_lane, list_people), with whoami the only conventional exception and it is idiomatic.
11 tools is well within the sweet spot and every tool corresponds to a concrete board operation; nothing feels padded or missing at the count level.
Task lifecycle is fully covered (create/get/update/move/delete) plus board reads, lane creation/renaming, and people listing. Gaps: no delete_lane or lane reordering, and no project creation, which could be a dead end for cleanup or lane restructuring.
Maintenance
Related MCP Connectors
Kanban boards your AI agent can use: add, complete, move and recall tasks with your team.
Kanban boards, cards, checklists and team chat for AI agents. Hosted, OAuth sign-in, free.
Kanban tasks and project notes for AI clients, with OAuth and per-project read or write grants.
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to create, update, list, and delete tasks on a Kanban board via the Model Context Protocol, supporting multi-project management and real-time collaboration.109MIT
- AlicenseBqualityDmaintenanceEnables AI agents to manage kanban boards with tasks, including creating boards, items, moving between columns, and searching.81MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to manage Kanban tasks, boards, teams, and checklists via natural language, with full CRUD operations and live updates.MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to read and write a local kanban board, adding and editing cards, moving them between columns, managing projects, and writing update entries so their work is visible in real time.6 npm1MIT