# bradrisse/kanban-mcp architecture

> Architecture diagram of the GitHub repository bradrisse/kanban-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bradrisse/kanban-mcp
- Repository: https://github.com/bradrisse/kanban-mcp

## Overview

Kanban MCP is an MCP server that lets an AI assistant manage Planka projects and boards. The principal workflow is a client request over stdio, dispatch in the server, and Planka API operations; higher-level tools combine those operations for summaries, card details, and common workflows. The README documents broad management features, including time tracking. Some operation and tool wiring is supported by documentation or filenames rather than sampled implementation, so uncertain call relationships are omitted.

Main entry points: [`index.ts`](https://github.com/bradrisse/kanban-mcp/blob/main/index.ts) (MCP Server), [`common/utils.ts`](https://github.com/bradrisse/kanban-mcp/blob/main/common/utils.ts) (API Request), [`operations/boards.ts`](https://github.com/bradrisse/kanban-mcp/blob/main/operations/boards.ts) (Boards), [`tools/board-summary.ts`](https://github.com/bradrisse/kanban-mcp/blob/main/tools/board-summary.ts) (Board Summary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP Server"]
  node_mcp["MCP Server<br/>[index.ts]"]
  node_stdio["stdio Transport<br/>[index.ts]"]
end

subgraph group_tools["Workflow Tools"]
  node_summary["Board Summary<br/>[board-summary.ts]"]
  node_details["Card Details<br/>[card-details.ts]"]
  node_create_bundle["Create Card Bundle"]
  node_workflow["Workflow Actions"]
end

subgraph group_domain["Kanban Operations"]
  node_projects["Projects<br/>[projects.ts]"]
  node_boards["Boards<br/>[boards.ts]"]
  node_memberships["Board Memberships"]
  node_lists["Lists<br/>[lists.ts]"]
  node_cards["Cards and Time<br/>[cards.ts]"]
  node_tasks["Tasks<br/>[tasks.ts]"]
  node_comments["Comments<br/>[comments.ts]"]
  node_labels["Labels<br/>[labels.ts]"]
end

subgraph group_integration["Planka Integration"]
  node_request["API Request<br/>[utils.ts]"]
  node_setup["Admin Lookup<br/>[setup.ts]"]
end

node_assistant(("AI Assistant"))
node_planka{{"Planka API"}}

node_assistant -->|"sends MCP requests"| node_stdio
node_stdio -->|"delivers requests"| node_mcp
node_mcp -->|"returns results"| node_stdio
node_mcp -->|"dispatches summary"| node_summary
node_mcp -->|"dispatches details"| node_details
node_mcp -->|"dispatches creation"| node_create_bundle
node_mcp -->|"dispatches actions"| node_workflow
node_mcp -->|"dispatches operations"| node_projects
node_mcp -->|"dispatches operations"| node_boards
node_mcp -->|"dispatches operations"| node_memberships
node_mcp -->|"dispatches operations"| node_lists
node_mcp -->|"dispatches operations"| node_cards
node_mcp -->|"dispatches operations"| node_tasks
node_mcp -->|"dispatches operations"| node_comments
node_mcp -->|"dispatches operations"| node_labels
node_summary -->|"reads board"| node_boards
node_summary -->|"reads lists"| node_lists
node_summary -->|"reads cards"| node_cards
node_summary -->|"reads tasks"| node_tasks
node_summary -->|"reads comments"| node_comments
node_summary -->|"reads labels"| node_labels
node_create_bundle -->|"creates card"| node_cards
node_create_bundle -->|"creates tasks"| node_tasks
node_create_bundle -->|"adds comment"| node_comments
node_workflow -->|"reads and moves"| node_cards
node_workflow -->|"reads board"| node_boards
node_workflow -->|"reads lists"| node_lists
node_workflow -->|"updates tasks"| node_tasks
node_workflow -->|"adds comment"| node_comments
node_boards -->|"creates defaults"| node_lists
node_boards -->|"creates defaults"| node_labels
node_boards -->|"adds admin member"| node_memberships
node_boards -->|"looks up admin"| node_setup
node_projects -->|"calls API helper"| node_request
node_boards -->|"calls API helper"| node_request
node_memberships -->|"calls API helper"| node_request
node_lists -->|"calls API helper"| node_request
node_cards -->|"calls API helper"| node_request
node_tasks -->|"calls API helper"| node_request
node_comments -->|"calls API helper"| node_request
node_labels -->|"calls API helper"| node_request
node_setup -->|"looks up users"| node_request
node_request -->|"sends API requests"| node_planka

click node_mcp "https://github.com/bradrisse/kanban-mcp/blob/main/index.ts"
click node_stdio "https://github.com/bradrisse/kanban-mcp/blob/main/index.ts"
click node_summary "https://github.com/bradrisse/kanban-mcp/blob/main/tools/board-summary.ts"
click node_details "https://github.com/bradrisse/kanban-mcp/blob/main/tools/card-details.ts"
click node_create_bundle "https://github.com/bradrisse/kanban-mcp/blob/main/tools/create-card-with-tasks.ts"
click node_workflow "https://github.com/bradrisse/kanban-mcp/blob/main/tools/workflow-actions.ts"
click node_projects "https://github.com/bradrisse/kanban-mcp/blob/main/operations/projects.ts"
click node_boards "https://github.com/bradrisse/kanban-mcp/blob/main/operations/boards.ts"
click node_memberships "https://github.com/bradrisse/kanban-mcp/blob/main/operations/boardMemberships.ts"
click node_lists "https://github.com/bradrisse/kanban-mcp/blob/main/operations/lists.ts"
click node_cards "https://github.com/bradrisse/kanban-mcp/blob/main/operations/cards.ts"
click node_tasks "https://github.com/bradrisse/kanban-mcp/blob/main/operations/tasks.ts"
click node_comments "https://github.com/bradrisse/kanban-mcp/blob/main/operations/comments.ts"
click node_labels "https://github.com/bradrisse/kanban-mcp/blob/main/operations/labels.ts"
click node_request "https://github.com/bradrisse/kanban-mcp/blob/main/common/utils.ts"
click node_setup "https://github.com/bradrisse/kanban-mcp/blob/main/common/setup.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_stdio toneBlue
class node_summary,node_details,node_create_bundle,node_workflow toneAmber
class node_projects,node_boards,node_memberships,node_lists,node_cards,node_tasks,node_comments,node_labels,node_planka toneMint
class node_request,node_setup toneRose
class node_assistant toneIndigo
```

## Components

### MCP Server

- [MCP Server](https://github.com/bradrisse/kanban-mcp/blob/main/index.ts): `index.ts`
- [stdio Transport](https://github.com/bradrisse/kanban-mcp/blob/main/index.ts): `index.ts`

### Workflow Tools

- [Board Summary](https://github.com/bradrisse/kanban-mcp/blob/main/tools/board-summary.ts): `tools/board-summary.ts`
- [Card Details](https://github.com/bradrisse/kanban-mcp/blob/main/tools/card-details.ts): `tools/card-details.ts`
- [Create Card Bundle](https://github.com/bradrisse/kanban-mcp/blob/main/tools/create-card-with-tasks.ts): `tools/create-card-with-tasks.ts`
- [Workflow Actions](https://github.com/bradrisse/kanban-mcp/blob/main/tools/workflow-actions.ts): `tools/workflow-actions.ts`

### Kanban Operations

- [Projects](https://github.com/bradrisse/kanban-mcp/blob/main/operations/projects.ts): `operations/projects.ts`
- [Boards](https://github.com/bradrisse/kanban-mcp/blob/main/operations/boards.ts): `operations/boards.ts`
- [Board Memberships](https://github.com/bradrisse/kanban-mcp/blob/main/operations/boardMemberships.ts): `operations/boardMemberships.ts`
- [Lists](https://github.com/bradrisse/kanban-mcp/blob/main/operations/lists.ts): `operations/lists.ts`
- [Cards and Time](https://github.com/bradrisse/kanban-mcp/blob/main/operations/cards.ts): `operations/cards.ts`
- [Tasks](https://github.com/bradrisse/kanban-mcp/blob/main/operations/tasks.ts): `operations/tasks.ts`
- [Comments](https://github.com/bradrisse/kanban-mcp/blob/main/operations/comments.ts): `operations/comments.ts`
- [Labels](https://github.com/bradrisse/kanban-mcp/blob/main/operations/labels.ts): `operations/labels.ts`

### Planka Integration

- [API Request](https://github.com/bradrisse/kanban-mcp/blob/main/common/utils.ts): `common/utils.ts`
- [Admin Lookup](https://github.com/bradrisse/kanban-mcp/blob/main/common/setup.ts): `common/setup.ts`

### Other components

- **AI Assistant**
- **Planka API**

## Connections

- AI Assistant → stdio Transport: sends MCP requests
- stdio Transport → MCP Server: delivers requests
- MCP Server → stdio Transport: returns results
- MCP Server → Board Summary: dispatches summary
- MCP Server → Card Details: dispatches details
- MCP Server → Create Card Bundle: dispatches creation
- MCP Server → Workflow Actions: dispatches actions
- MCP Server → Projects: dispatches operations
- MCP Server → Boards: dispatches operations
- MCP Server → Board Memberships: dispatches operations
- MCP Server → Lists: dispatches operations
- MCP Server → Cards and Time: dispatches operations
- MCP Server → Tasks: dispatches operations
- MCP Server → Comments: dispatches operations
- MCP Server → Labels: dispatches operations
- Board Summary → Boards: reads board
- Board Summary → Lists: reads lists
- Board Summary → Cards and Time: reads cards
- Board Summary → Tasks: reads tasks
- Board Summary → Comments: reads comments
- Board Summary → Labels: reads labels
- Create Card Bundle → Cards and Time: creates card
- Create Card Bundle → Tasks: creates tasks
- Create Card Bundle → Comments: adds comment
- Workflow Actions → Cards and Time: reads and moves
- Workflow Actions → Boards: reads board
- Workflow Actions → Lists: reads lists
- Workflow Actions → Tasks: updates tasks
- Workflow Actions → Comments: adds comment
- Boards → Lists: creates defaults
- Boards → Labels: creates defaults
- Boards → Board Memberships: adds admin member
- Boards → Admin Lookup: looks up admin
- Projects → API Request: calls API helper
- Boards → API Request: calls API helper
- Board Memberships → API Request: calls API helper
- Lists → API Request: calls API helper
- Cards and Time → API Request: calls API helper
- Tasks → API Request: calls API helper
- Comments → API Request: calls API helper
- Labels → API Request: calls API helper
- Admin Lookup → API Request: looks up users
- API Request → Planka API: sends API requests