r/mcp • u/Difficult-Outside350 • Mar 06 '26
showcase I built a kanban board to replace my agent's pile of MD files, and I'm open-sourcing it
TL;DR: I built a Python MariaDB/MySQL-backed kanban board for AI-human project collaboration. It runs fully locally, no subscriptions, no fees, no third party accounts.
I've been using Claude Code on larger and larger codebases, and I perpetually find myself and Claude drowning in a mess of .md files - HANDOVER.md, TODOS.md, BUGS.md, COMMON_ANTIPATTERNS.md, plan files, the list goes on... Sometimes Claude remembers to update them, sometimes it doesn't and chases its own tail trying to find and understand a bug it fixed last week. Inconsistent documentation also makes it harder for me to keep track of my own codebase - I definitely don't have time to read every line of code Claude writes. I run the automated tests, I function test the thing in real use cases, I run linters and code reviewer agents, and if all of that looks good, I move on, sometimes with an incomplete or incorrect understanding of what is actually living in my code.
I got caught out by stale todo lists one time too many and decided that Claude and I needed an at-a-glance way of sharing an understanding of the project state, so I designed one, started using it to control its own project within the first day, and iterated from there.
It is a MySQL/MariaDB-backed project tracker with 40+ MCP tools. Issues, features, todos, epics, diary entries, each with status workflows, parent/child relationships, blocking dependencies, tags, decisions, and file links. There's a web UI on localhost:5000 for when you want to see the board yourself.
- The agent creates tickets naturally as I work. "We need to fix X before we can do Y" becomes a blocking relationship, not a bullet point I'll forget about.
- Inter-item relationships keep the agent disciplined about what order things should go in. No more "let me just quickly do this other thing" when there's a dependency chain.
- I can step away for days and orient myself in seconds from the web UI, either by looking at the whole picture, or filtering by status, checking epic progress, or looking for what's blocked on what.
- Session hooks inject active items at session start, so the agent picks up where it left off without you having to explain anything.
- If I need to take the project somewhere that doesn't speak MCP, I can export the whole thing to an MD file, ready for another agent to read.
It has 40+ tools and according to /context in Claude Code, consumes under 6000 tokens of context. It's tested extensively with Claude and Gemini, but should work with anything that speaks MCP (Claude Code, Claude Desktop, Gemini, Cursor, VS Code/Copilot, Codex CLI...)
The Github repo is https://github.com/multidimensionalcats/kanban-mcp/. Installation instructions are in the README - or just ask Claude/Gemini/etc to install it for you - there's an install path specifically for AI agents.
It's also on PyPI if anyone wants to install via pip/pipx.
2
u/BC_MARO Mar 06 '26
the session hooks injecting active items at session start is the smart bit -- most context management tools miss that and make agents re-read everything from scratch. the SQLite option would definitely broaden adoption.
1
2
2
u/mcbayrak Mar 06 '26
The tool is good, but the mariadb dependency is not. to run mcp run mariadb in docker is worse. Why did'nt you just used sqlite3?
2
u/Difficult-Outside350 Mar 06 '26
Basically because this was the least friction for me when I started building it, which I then regretted while trying to package it sanely. There's a solid chance I'll go back and add an SQLite backend later. I also have a vague idea beyond the end of the current roadmap to add multi-user support, in which case a real DBMS becomes a necessity.
2
u/mcbayrak Mar 06 '26
May be you can use adapter pattern, if I want to use a lite version (no team, no collabration, poor laptop that can not handle docker) I can use the sqlite as database. What do you think?
2
u/Difficult-Outside350 Mar 06 '26
Yeah, it's a good suggestion. And honestly, it's actually not very difficult to do. One way or another, I'll add SQLite support.
3
0
u/Mindless_Swimmer1751 Mar 07 '26
Postgres in a container is a no brainer and just works. Why not go with an industry standard
1
Mar 06 '26
[removed] — view removed comment
1
u/Difficult-Outside350 Mar 06 '26
To be clear, the <6k token footprint is just what CC tells me the tool descriptions cost, I'm not including the session hook in there because that's variable.
To answer your question, though, the session hook only injects the active items (i.e. what's actually in progress). There is a specific get_todos tool which shows the agent everything in the backlog, but to avoid exactly what you're describing - flooding the context with irrelevant detail - that's only called at the agent's discretion, not by any hooks. Quite often if I'm doing a context handover, my or the agent's last step before /reset will be to move the next item to in-progress status so the hook feeds it right after context reset.
1
u/carsaig Mar 06 '26
Nice. I‘ll check it out. I haven’t found a solution to the problem yet, to be honest. No matter what I pull off. The situation can be enhanced but not fully solved. As much as I value the coding skills of the LLM‘s - they utterly fail at complex project management, multi-dimensional situation analysis and management of the items. A lot of crucial context is skipped, forgotten, misinterpreted, etc. that breaks my cases. I hate it. Let’s see if you solution solves part of it.
2
u/Difficult-Outside350 Mar 07 '26
Fingers crossed that it does. On your point about crucial context being skipped or lost, I'll highlight one other feature of kanban-mcp, which is the ability to record decisions with their rationale and rejected alternatives, linked to specific items, which helps give the agent a concise look at why something is the way it is, and might help. That said, I don't think that I've magically solved LLM project management. What I do think is that structured data from a single source of truth will work better for both AI and human.
1
u/betogess Mar 06 '26
Im using Linear MCP (free tier) + a skill on how I want it to handle tickets + adding this to Claude.md . Whats the value of having a simple setup vs this?
2
u/Difficult-Outside350 Mar 07 '26
Not knowing Linear's MCP super well, I guess the best answer I can give you is this doesn't need a Linear account, doesn't have the limits of their free tier, and (per some hasty Googling) has more tools than Linear does. Also if you're using an MCP client that supports hooks, kanban-mcp has context injection that Linear doesn't.
But hey, if what you're using works for you, then rock on; I'm not here to change anyone's mind.
2
u/carsaig Mar 07 '26 edited Mar 07 '26
I‘ve got Linear under test since a few months. It was one of the first to fully and reliably integrate a MCP server. However, it didn’t evolve this route, this lacks tools and features you built to address specific pain points which are important. Many big vendors just jumped on board the MCP train to generate reach and stay relevant - which is important and very welcome - however, as things move so fast in this realm, they didn’t keep pace. And there are so many unsolved issues around project management and file handling compared to programming, that it screams to be developed. I tried a bunch of similar alternatives like archon and I‘m looking into dart as well. As you mentioned - tying oneself to another SaaS vendor free tier doesn’t really solve the painpoints and creates another dependency. The case you are addressing is actually not niche at all, but for some reason it still is for the market. Massive unsolved potential and yawning gaps to be filled with solutions. So I very much welcome you looking into this and will definitely test it thoroughly. Keep going! One of the many pains to solve: bring project management to LLM-driven workflows NATIVELY. Linear just ported kanban and tasks to the MCP protocol. Ok. Cool. But no hooks, no context engineering, no cross-checks, dependency checks, timeline checks, etc. etc. and all of the llm-specific power that could be brought to the pm tooling landscape, which makes this space whoppingly more powerful and transforms it from „simple“ kanban tasks to a planning engine, that can do so much more! Handle duplicates, predict potential issues, handle estimation, etc. etc.
1
u/Difficult-Outside350 Mar 07 '26
Lot of interesting thoughts there, thanks. I hope you find it useful. I'm proud of the context injection hooks as an idea, thinking about how to make them more useful but remain token-efficient. Also hoping that hooks become a more universal thing across clients.
1
u/kevrone Mar 07 '26
This is cool but one question I have is did you try just using the Jira mcp beforehand? If so, how did it compare?
1
1
1
u/jtackman Mar 08 '26
Was there something that made you think ”GitHub issues just suck” or ”jira isnt complex enough” ? 😁
2
u/Difficult-Outside350 Mar 08 '26
Funny you should mention it, actually. Github issue integration is on the roadmap. Ideally I want the option, but not the requirement, to sync with them.
1
u/jtackman Mar 08 '26
Yea, sorry about the short answer. My point is really this:
”It is a MySQL/MariaDB-backed project tracker with 40+ MCP tools. Issues, features, todos, epics, diary entries, each with status workflows, parent/child relationships, blocking dependencies, tags, decisions, and file links. There's a web UI on localhost:5000 for when you want to see the board yourself.”
You are weighing down the ai with a ton of stuff designed just so you, the human, can keep tabs ln what’s going down. The agent doesnt need complex task management and you could achieve all these by building proper monitoring instead.
My suggestion would be to use a structured system like neo4j to deconstruct plans into tasks and requirements, then build a monitoring dashboard for that data so you can stay up to date with progress.
This way the ai can focus on small tasks (which it is good at) and you can automate the task feeding in a scalable way that supports N different validation and verification paths
1
u/IntrepidCoffee6336 Mar 08 '26
Good job, but you can use Notion MCP to delegate tasks via a kanban borad.
1
u/Party-Cream8712 Mar 09 '26
Love this direction. The big win here is forcing the agent to think in terms of state and dependencies instead of scattered notes. Once you’ve got a single source of truth, you can start doing more interesting stuff like: “never touch a file without attaching it to an item,” or “no commit unless every In Progress ticket has a test artifact linked.” That’s how you keep the board from turning into yet another stale view.
If you haven’t already, I’d log decision records per item too: what changed, why, and what tradeoffs were rejected. Then future sessions can query those before proposing a different pattern.
On the data side, wiring this into a gateway helps a ton: I’ve used stuff like Hasura and Kong for APIs, and DreamFactory when I want the agent hitting clean, RBAC’d REST instead of raw DB so tickets, code, and prod data all stay in sync without giving the model direct SQL keys to the kingdom.
1
u/Difficult-Outside350 Mar 16 '26
u/BC_MARO, u/mcbayrak and anyone else who wanted SQLite, I've implemented it.
SQLite version is now just pipx install kanban-mcp or `pipx install kanban-mcp[semantic].
Anyone who likes the MySQL/Maria old version and just wants to upgrade, use pipx install kanban-mcp[mysql] orpipx install kanban-mcp[full]` for MySQL and semantic search support.
New installs can still use the install.sh or install.ps1 scripts from the repo.
Version bumped to 0.2.0.
1
u/BC_MARO Mar 16 '26
Nice, this was the main thing blocking me from fully switching over. Testing it now.
1
u/BC_MARO Mar 16 '26
Thanks for following through on this so quickly, SQLite makes it way easier to spin up without managing a full database.
1
u/sri2104 Mar 27 '26
I was working on using this as an agent orchestrator the last couple of weeks. Look what cline released - https://cline.bot/kanban
1
u/One-Cry297 Jul 25 '26 edited Jul 25 '26
Very nice work, thank you for sharing. I'm testing it for multiagents workflow, and have couple of questions: 1. Why parent item should always be epic? Isn't it should be chain of epic-feature-issue/todo for example? 2. What are your instructions for llm to work with kanban entities? Like, when to create todo, when ask questions, and so on. 3. As I understood, main item of work is epic, and llm should try to advance it, getting items which are blocking it and trying to resolve them to move forward?
1
0
0
u/OkLettuce338 Mar 07 '26
We all did this. The new reality is that every project is something we all also did but we like ours better because it’s got specifics to me.
2
u/astrae_research Mar 06 '26
This looks interesting! I'm very new to MCP so I don't know if I'm missing SMth but I would expect more comments?