planka-mcp
A stdio MCP server that lets LibreChat agents read and manipulate self-hosted PLANKA kanban boards — create cards, move tasks, manage labels, and add comments directly from chat.
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
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
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.
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