Integrates with Obsidian vaults by managing tasks as plain Markdown checkbox lines on a visual Kanban board. Allows AI assistants to list boards, find cards, add tasks, move or close cards, comment on cards, and keep the board in sync with Obsidian notes.
Save tasks from Claude and Codex to a visual Kanban board — kept as plain Markdown in your Obsidian vault.
Tell the Claude app or the Codex app “add to kanban: renew the car insurance by Nov 30” — the card appears on your board
and as a - [ ] line in your notes. Drag it in the browser, tick it in Obsidian: both stay in sync.
From Claude & Codex · Quick start · Connect your AI · Screenshots · How it works · FAQ · Docs
Demo data. The chat panel is drawn; the board and the new card are real — the card also became line 19 of Tasks/Personal.md. Real screenshots of the Claude and Codex apps are just below.
Ask your AI app in plain words. Moments later the task is a card on your board and a - [ ] line in your Obsidian note — no copying, no switching apps. Both apps reach the board through the MCP server that comes with it (setup).
Real screenshots of the Claude desktop app (Claude Code in its Code tab; it answered in its user's language, Russian) and the Codex app, both connected to a demo board. The titles, the arrows and the purple outline around each new card were added on top.
Related MCP server: sanban
📝 Your tasks stay plain Markdown. Cards are ordinary - [ ] lines in your Obsidian notes. No new format, no account, nothing to import or export.
👀 See everything at a glance. Columns, priorities, colors, due dates, checklists and comments — a board instead of a long list.
🤖 Your AI apps keep the board up to date. Ask the Claude app, Claude Code or the Codex app to add a task, move it, comment on it or close it. When it is unclear which board you mean, the assistant asks one short question instead of guessing.
🏠 Runs on your own computer. The board is a small web app on localhost. Your tasks do not leave your machine unless you decide to publish the board.
Pick the way that suits you. Each ends with the board open at http://localhost:4000.
Open Claude Code on your Mac and paste:
Install Obsidian Kanban on this Mac by following
https://github.com/sergi039/obsidian-kanban-app/blob/main/docs/personal-install.mdClaude asks which Obsidian vault to use and does the rest with one script: no administrator password, everything stays in your home folder. Afterwards, in a new Claude Code session, type “add to kanban: check the install” and watch the card appear. Details: docs/personal-install.md (Apple Silicon Mac).
You need Node.js 22 and pnpm.
git clone https://github.com/sergi039/obsidian-kanban-app.git
cd obsidian-kanban-app
pnpm installCreate config.boards.json next to package.json and point it at your vault and a task file:
{
"vaultRoot": "/path/to/your/Obsidian/Vault",
"boards": [
{ "id": "personal", "name": "Personal", "file": "Tasks/Personal.md",
"columns": ["Backlog", "This week", "In progress", "Done"] }
],
"defaultColumns": ["Backlog", "In progress", "Done"]
}pnpm build
SERVE_STATIC=1 pnpm --filter @kanban/api startThe task file is any note with checkboxes:
- [ ] ⏫ Renew passport before the summer trip
- Book an appointment online
- [ ] Plan the Lisbon weekend
- [x] Pay the electricity bill⏫ marks a high priority, indented lines become sub-items, - [x] is done.
Put the same config.boards.json into a config/ folder next to docker-compose.yml, then run VAULT_PATH=/path/to/vault docker compose up -d and open http://localhost:4000. Details: reference.
The app includes an MCP server — the standard way AI apps use tools. With it your assistant can list your boards, find cards, add a task, add to a card, move or close it, comment on it and follow up an email. It talks only to your local board, never directly to your files.
After the one-script install there is nothing to do: it registers the server for Claude Code, and for Codex when Codex is on the Mac.
Otherwise, step 1. Build the MCP server (the board must be running, see above):
pnpm --filter @kanban/mcp buildStep 2. Add it to your assistant (replace the path):
Assistant | Status | How |
Claude Code (terminal and the Code tab of the Claude app) | ✅ Local MCP | one command — see below |
OpenAI Codex (app, CLI, IDE extension) | ✅ Local MCP | one command — see below |
Claude Desktop (chat) | ✅ Local MCP | Settings → Developer → Edit Config — see below |
ChatGPT chat, claude.ai in the browser or on the phone | 🚧 Not yet | they need a remote HTTPS MCP server with sign-in, which this project does not ship (why) |
claude mcp add --scope user obsidian-kanban -e KANBAN_API_URL=http://127.0.0.1:4000 \
-- node /path/to/obsidian-kanban-app/apps/mcp/dist/server.jsCheck with /mcp in a new session.
codex mcp add obsidian-kanban --env KANBAN_API_URL=http://127.0.0.1:4000 \
-- node /path/to/obsidian-kanban-app/apps/mcp/dist/server.jsThe Codex app, the CLI and the IDE extension read the same ~/.codex/config.toml. Check with /mcp in Codex. Codex uses the tools without asking, except rewriting a card's whole description, which it asks you to approve.
Settings → Developer → Edit Config opens claude_desktop_config.json. Add:
{
"mcpServers": {
"obsidian-kanban": {
"command": "/absolute/path/to/node",
"args": ["/path/to/obsidian-kanban-app/apps/mcp/dist/server.js"],
"env": { "KANBAN_API_URL": "http://127.0.0.1:4000" }
}
}
}The app may not see your shell's PATH, so give node by its full path (which node). Quit Claude Desktop completely and open it again.
If the board runs with API_TOKEN, add KANBAN_API_TOKEN with the same value. Card links in the answers open KANBAN_APP_URL when you set it (your board's public address), else KANBAN_API_URL.
Step 3. Ask in plain words:
You say | What happens |
“add to kanban: renew the car insurance by Nov 30” | A card in the first column of the right board. Several boards fit? The assistant asks which one. |
“put ‘prepare the Q4 roadmap’ on my Work board” | The card goes straight to the board you named. |
“make a task from this email” (an assistant that can read your mail) | The card links back to the email; the same thread never becomes a second card. |
“which boards do I have?” | Boards, columns, categories and priorities. |
More: docs/desktop-mcp.md — the tools, tasks from email, a board on another Mac, the safety model.
Obsidian stays the source. Each task line in your note is a card; ticking [x] in Obsidian moves it to Done, and dragging it back on the board unticks it.
Changes show up in under a second. A file watcher picks up edits in Obsidian; edits on the board are written back to the file. Every open tab updates live.
Nothing gets lost. The card's column is kept in an invisible comment on its line (<!-- kb:id=… kb:col=… -->, an HTML comment that Obsidian's reading view hides), so the board survives even if its database is deleted.
Extras live next to the app. Checklists, comments, categories and reminders are stored in a local SQLite file, not in your notes.
Views — board with drag & drop, table with inline editing, saved views, filters and sorting
Cards — #1-style IDs, descriptions, checklists, links, comments, due dates, custom fields
Organize — priorities, colored categories, collapsible columns, bulk move and close, trash with restore
Remind — in-app and browser reminders; macOS notifications, Calendar and Mail through a small local agent (reminders)
Calendars — Outlook and Google events linked to a card show up on it
Automate — rules such as “when a card moves to Done, set a field”
Stay safe — runs on localhost, refuses requests from other web pages, backs up its config and database on every start
The full list is in the reference.
No. It is a small web app that runs next to Obsidian and reads and writes the same Markdown files. Obsidian does not even need to be open.
The plugin draws a board inside Obsidian from a file in its own board format. Obsidian Kanban keeps your ordinary checklists as they are, opens them as a board in any browser, adds a table view, reminders and comments, and lets AI assistants add tasks through MCP.
No — any folder of Markdown files works. Obsidian is simply the nicest place to edit them.
Tasks stay in your Markdown files; card extras stay in a SQLite file inside the app folder. The app talks to the internet only for what you turn on yourself, such as reading your Outlook or Google calendar. Your AI assistant sees what you ask it to add, the same as any chat.
The board is a web page, so you can publish it behind a sign-in (the author uses Cloudflare Access — see the reference). Tasks edited in Obsidian on your phone reach the board through whatever already syncs your vault.
The Codex part of OpenAI's apps — yes, through the same local MCP server. Regular ChatGPT chat can only use MCP servers on a public HTTPS address, which this project does not provide yet.
Guide | What is inside |
The one-script Mac install, daily use, update, uninstall | |
The tools, client setup, tasks from email, a board on another Mac, safety model | |
Reminder channels, the macOS agent, email follow-ups | |
Configuration, Markdown format, sync internals, security, calendars, troubleshooting, project structure | |
What changed and when |
Issues and pull requests are welcome. pnpm test runs the test suites; the reference shows the development setup with hot reload.
MIT. Obsidian Kanban is an independent project, not affiliated with Obsidian, Anthropic or OpenAI; their names are trademarks of their owners.
This server cannot be deployed
Read and manage your EasyKanban kanban boards: to-do summaries, create, update, and move cards.
A todo and task board in kanban form, driven from chat with full CRUD.
Kanban boards your AI agent can use: add, complete, move and recall tasks with your team.
Kanban tasks and project notes for AI clients, with OAuth and per-project read or write grants.
