Content
# Hermes Kanban MCP Server
A standalone [Model Context Protocol](https://modelcontextprotocol.io)
server that exposes the [Hermes Agent](https://github.com/) Kanban
SQLite board to **any** MCP-capable client — Claude Code, Codex,
Cursor, VS Code, etc. The server reads and writes the **same** DB
used by Hermes itself, so tasks created by an external AI agent are
dispatched by Hermes, and tasks created by Hermes can be read,
commented on, and completed from your editor.
## Why
Hermes Agent's Kanban board is its cross-profile coordination
primitive: the dispatcher claims tasks, spawns workers, tracks runs
and handoffs, and resolves dependencies. Until now, only Hermes-built
agents could touch this board. This MCP server lets any external
agent participate without depending on the Hermes Python package.
## Tools (13)
| Tool | Purpose |
|---|---|
| `kanban_list` | List tasks (filter by status / assignee / tenant). |
| `kanban_show` | Full task state: body, parents, children, comments, events, runs, pre-formatted worker_context. |
| `kanban_context` | Just the formatted worker_context markdown (lighter than `kanban_show`). |
| `kanban_create` | Create a task (with optional parents, tenant, priority, skills, workspace_kind, idempotency_key, max_runtime_seconds, triage). |
| `kanban_complete` | `running|ready|blocked → done` with summary + structured metadata. |
| `kanban_block` | `running|ready → blocked` with reason. |
| `kanban_unblock` | `blocked → ready`. |
| `kanban_claim` | Atomic `ready → running`, returns workspace_path. |
| `kanban_assign` | (Re)assign profile. Refuses while task is running. |
| `kanban_link` | Add parent→child dependency. Cycles rejected. |
| `kanban_unlink` | Remove parent→child dependency. |
| `kanban_comment` | Append a markdown comment to a task's thread. |
| `kanban_heartbeat` | Liveness signal for long-running operations. |
## DB compatibility
The server uses Hermes's exact schema — `tasks`, `task_links`,
`task_comments`, `task_events`, `task_runs`, `kanban_notify_subs` —
with the same WAL pragmas and `BEGIN IMMEDIATE` write transactions.
SQLite serializes concurrent writers, so this server can coexist
with a running Hermes dispatcher on the same DB without coordination.
## Installation
Requires Python 3.10+ (Hermes itself targets 3.11+, but this server uses
only stdlib features available since 3.10).
```bash
git clone <this-repo> /mnt/s3vo/hermes-kanban-mcp
cd /mnt/s3vo/hermes-kanban-mcp
python3 -m venv .venv
.venv/bin/pip install 'mcp[cli]>=1.0.0'
# (optional) run the test suite
.venv/bin/pip install pytest
.venv/bin/pytest tests/
```
## Environment variables
The DB path is resolved from these env vars (highest precedence first):
| Variable | Effect |
|---|---|
| `HERMES_KANBAN_DB` | Pin the DB file path directly. Highest precedence. |
| `HERMES_KANBAN_HOME` | Root that anchors kanban paths. Falls back to `HERMES_HOME`, then `~/.hermes`. |
| `HERMES_HOME` | Root used when `HERMES_KANBAN_HOME` is unset. |
| `HERMES_KANBAN_BOARD` | Board slug. `default` (the only board on fresh installs) lives at `<root>/kanban.db`; other boards at `<root>/kanban/boards/<slug>/kanban.db`. |
| `HERMES_KANBAN_TASK` | Implicit `task_id` for `kanban_show` / `kanban_complete` / `kanban_block` / `kanban_comment` / `kanban_heartbeat` / `kanban_context` when omitted. Useful inside a worker spawned by the Hermes dispatcher. |
| `HERMES_PROFILE` | Default `author` for `kanban_comment` (falls back to `mcp-client`). |
## Client setup
### Claude Code
```bash
claude mcp add kanban -- /mnt/s3vo/hermes-kanban-mcp/.venv/bin/python /mnt/s3vo/hermes-kanban-mcp/server.py
```
Inside Claude Code, type `/mcp` to verify the server is connected, or
just ask the agent to "list my kanban tasks" — the tool router will
dispatch to `kanban_list`.
### Codex / Cursor / VS Code
Add an entry to your MCP config (`.mcp.json` or the client-specific
file):
```jsonc
{
"mcpServers": {
"kanban": {
"command": "/mnt/s3vo/hermes-kanban-mcp/.venv/bin/python",
"args": ["/mnt/s3vo/hermes-kanban-mcp/server.py"],
"env": {
"HERMES_KANBAN_BOARD": "default"
}
}
}
}
```
Use the bundled `.mcp.json` in this repo as a reference.
### Hermes (dogfood)
```bash
hermes mcp add kanban --command /mnt/s3vo/hermes-kanban-mcp/.venv/bin/python /mnt/s3vo/hermes-kanban-mcp/server.py
hermes mcp test kanban
```
## Verification
End-to-end sanity:
```bash
# 1. server starts and waits on stdio
echo "" | .venv/bin/python server.py # press Ctrl-C to exit
# 2. unit tests pass
.venv/bin/pytest tests/
# 3. cross-tool DB compatibility (Hermes installed)
hermes kanban list # see what Hermes shows
# then in Claude Code:
# "List my kanban tasks" # should show the same rows
```
## Status flow recap
```
triage ──spec──▶ todo
│
│ all parents done
▼
running ◀──claim── ready ◀── (recompute_ready)
│
├─ complete ──▶ done
├─ block ──▶ blocked ──unblock──▶ ready
└─ archive ──▶ archived
```
## Limitations / scope
- No board management commands (use Hermes `hermes kanban boards ...`).
- No notification subscriptions (`kanban_notify_subs`) read/write.
- No workflow template (`workflow_template_id`) control.
- stdio transport only (no SSE/HTTP).
- Tools always operate against the **single** board resolved from env
at startup. Switch boards by setting `HERMES_KANBAN_BOARD` before
launching the server.
