planka-mcp
A stdio MCP server that let LibreChat agents drive self-hosted PLANKA kanban boards from chat — retired in 2026 when a licence change took Planka, and the boards with it.
highlights
- Full PLANKA surface area — navigation, cards, lists, tasks, labels, and comments
- Zod v4 entity schemas generated from Planka's OpenAPI spec via typed-openapi
- Published to private Gitea npm registry; spawned by LibreChat via `npx -y @cortlan/planka-mcp`
- v2 dropped the SSO attempt for a bot user API key after Planka's redirect rules blocked OIDC
- Archived September 2026 — Planka itself was retired, and the boards it spoke to no longer exist
Overview
Built to give Claude agents access to my self-hosted PLANKA boards via LibreChat. The goal was practical: automate task management, card creation, and status updates without leaving the chat interface. It covers PLANKA’s full surface — navigation, cards, lists, tasks, labels, and comments — as a set of MCP tools spawned by LibreChat via npx.
planka-mcp Evolution
- 2026-02v1.0.0 — initial release, core PLANKA tool coverage
- 2026-07-04SSO attempt via Authelia — blocked by Planka redirect rules
- 2026-07-05Pivot to bot user + API key · typed-openapi codegen · Zod v4 · CI/CD fixes
- 2026-09-09Archived — Planka retired in favour of Cairn
Architecture
The server is a pure stdio MCP process — LibreChat spawns it via npx -y @cortlan/planka-mcp and communicates over stdin/stdout. Auth is a single PLANKA_API_TOKEN environment variable bound to a dedicated bot user; no sessions, no OAuth.
Entity schemas are generated from Planka’s OpenAPI spec using typed-openapi, which produces Zod v4 types in src/generated/planka.ts. The MCP layer wraps those types and exposes named tools across PLANKA’s full surface area.
The package is published to my private Gitea npm registry at git.cortlan.dev.
The SSO Attempt
The trigger for v2 was the homelab SSO migration. The idea: proxy MCP auth through Authelia so the agent would act as my actual Planka user via OIDC rather than a shared account. It didn’t work. Planka enforces strict redirect rules that break the OIDC flow in this configuration — no amount of Authelia config resolved it.
The pivot was straightforward: a dedicated bot user with a static API key. Simpler, more reliable, and correct in practice since the agent is acting on behalf of the homelab owner anyway. Once unblocked, the surrounding cleanup followed quickly — codegen, Zod v4, and CI/CD header fixes for the Gitea registry.
Archived
Planka 2.2.0 dropped the table backing OIDC and moved single sign-on behind a €36/month floor for a single user, freezing the 2.1.1 instance unpatched. The same redirect rules that blocked the SSO attempt in July turned out to be the smaller problem.
Rather than migrate to another board that would make the same move eventually, I imported the boards into Cairn and retired the Planka instance. This server was archived on 2026-09-09. Its successor, @cortlan/cairn-mcp, is a thin wrapper over Cairn’s own REST contract rather than a translation layer over somebody else’s.
learnings
- PLANKA enforces strict redirect rules that make per-user OIDC impractical — a dedicated bot user is the right call when the agent acts on behalf of one person anyway
- Codegen from an OpenAPI spec keeps entity validation in sync with the upstream API without manual maintenance
- When the agent acts on behalf of a single owner, a bot user with a static API key is simpler and more reliable than any SSO scheme
- An integration against source-available software is one licence change from obsolete