Hermes Kanban MCP (hermes-kanban-mcp-vn)

Restricted stdio MCP bridge that submits durable work to an existing Hermes Kanban board. It does not create another task database and does not expose arbitrary shell, workspace, profile or model selection.

Architecture: MCP Hub --stdio/uvx--> MCP --HTTPS bearer--> restricted backend --fixed argv--> Hermes Kanban.

The dashboard token is intentionally not used because it grants broad dashboard access. Both sides enforce board/assignee allowlists. Keep the backend private (loopback, VPN, or authenticated reverse proxy). ready requires the profile on disk plus explicit inclusion in HERMES_KANBAN_READY_ASSIGNEES after runtime/provider checks. Creating a task does not authorize production deployment, destructive actions, outbound messages, or spending.

MCP Hub install (after PM approval and publish)

{"mcpServers":{"hermes-kanban":{"command":"uvx","args":["hermes-kanban-mcp-vn==0.1.0"],"env":{"HERMES_KANBAN_URL":"https://hermes-kanban.internal.example","HERMES_KANBAN_TOKEN":"<secret-from-hub-secret-store>","HERMES_KANBAN_ALLOWED_ASSIGNEES":"developer,project-manager","HERMES_KANBAN_ALLOWED_BOARDS":"default","HERMES_KANBAN_TIMEOUT":"20"}}}}

Never commit tokens or put them in command arguments.

Backend contract

Run on the Hermes host with the same board storage/config as /opt/hermes/bin/hermes:

HERMES_KANBAN_BACKEND_TOKEN='<secret>' HERMES_KANBAN_CLI=/opt/hermes/bin/hermes \
HERMES_KANBAN_ALLOWED_ASSIGNEES=developer,project-manager \
HERMES_KANBAN_READY_ASSIGNEES=developer,project-manager \
HERMES_KANBAN_ALLOWED_BOARDS=default \
uvx --from hermes-kanban-mcp-vn==0.1.0 hermes-kanban-backend

Authenticated routes: GET /v1/agents, POST /v1/tasks, GET /v1/tasks/{id}, POST /v1/tasks/{id}/comments. /healthz contains no board data. Use TLS and permit only MCP Hub source addresses.

Verify and publish

uv sync --extra dev
uv run pytest -q
uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run mypy src
uv build
uv run python scripts/mcp_smoke.py

The protocol smoke uses a loopback fake backend; it is not proof of live Hermes integration. After PM approval Linus publishes with UV_PUBLISH_TOKEN='<secret-store>' uv publish, starts the restricted backend, pins the Hub package version, and validates on an isolated board. Roll back by restoring the previous Hub package pin and stopping the backend; existing tasks remain durable.