zentra-mcp
This MCP server exposes Zentra's Task board, Sprint, and Vault APIs as tools Claude can call directly.
Tasks: create tasks with title, project tag, type, status, priority, description, and optional parent/sprint; list tasks filtered by tag, type, status, or parent; move tasks to a new status and optionally into a sprint.
Sprints: list sprints, optionally filtered by status (e.g. OPEN), and use the returned sprint id to file tasks into that sprint.
Vault: create Vault pages with content, parent folder, and tag; list the Vault page tree or a page's children; upload a local file as an attachment to a page.
Authentication: supports interactive login (JWT stored locally) or
ZENTRA_TOKENfor unattended use, with API base URL overridable viaZENTRA_API_URL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zentra-mcp create a task to fix the login flow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
zentra-mcp
MCP server exposing Zentra's Task and Vault APIs as tools Claude can call directly, from any project, not just from inside the Zentra repo:
Tool | What it does |
| Create a task on the board, optionally filed straight into a sprint |
| List tasks, filtered by tag/status/type/parent |
| Move a task to a new status, optionally assigning it to a sprint |
| List sprints, optionally filtered by status (e.g. OPEN) |
| Create a Vault page, optionally with content, a parent folder (by id or name), and a tag |
| List the Vault page tree, optionally narrowed to one page's children |
| Upload a local file as an attachment on a Vault page |
zentra_sprint_list resolves sprints (e.g. the OPEN one) by id, and that id can
then be passed as sprintId to zentra_task_create or zentra_task_move to
put a task in a sprint.
Extracted from the Zentra monorepo (packages/mcp) so that Zentra's sibling
projects can use it without checking out Zentra. It builds standalone: the few
task-board and Vault types it needs are vendored in src/board-types.ts rather
than imported from @zentra/shared.
Setup (one time)
Install and build:
yarn install && yarn buildAuthenticate. Two ways:
Interactive — run in a real terminal, not through Claude, since this is the only place your password is typed:
node dist/cli.js loginThis writes a JWT to
~/.config/zentra-mcp/credentials.json(mode600). The JWT expires after 7 days; re-run when a tool call reports "Session expired."Unattended — set
ZENTRA_TOKENto a long-lived service token, which takes precedence over the credentials file. This is how the scheduled daily runs authenticate; seedocs/service-token.mdin the Zentra repo for how to mint one.Register the server with Claude Code at user scope, so it's available in every project:
claude mcp add zentra-mcp --scope user -- sh "$(pwd)/bin/zentra-mcp.sh"bin/zentra-mcp.shinstalls dependencies whennode_modulesis missing and builds whendist/is missing or stale (anysrc/*.tsnewer thandist/cli.js), then execs the server. The missing case matters for fresh checkouts, where MCP stdio servers are spawned before anything has had a chance to build; the stale case matters after everygit pull, since an out-of-datedist/otherwise gets served silently and new tools never show up. Build output goes to stderr so stdout stays a clean protocol channel.Claude Code reads a server's tool list once, when it spawns the server at session start. Restart the session after changing tools — a running session will not pick them up.
Related MCP server: Procrastinator MCP Server
Configuration
ZENTRA_TOKEN— bearer token to authenticate with, preferred over~/.config/zentra-mcp/credentials.json. Used by unattended automation.ZENTRA_API_URL— override the API base URL (defaults to the production Render deployment). Useful for developing against a local API.
Project tags
Every task carries a tag naming its project, and a Vault page created via
zentra_vault_create_page can optionally carry one too.
Zentra's API is migrating tags from free text (tags: string[]) to a
registry (GET /api/tags, tagIds: string[]), but this server ships on its
own schedule, not in lockstep with that API — so it detects which one it's
talking to (by probing GET /api/tags once per session) and works either
way, with no configuration needed:
Registry available: a
tagname is resolved to its registered id case-insensitively. Creating a task, or tagging a page, with a name that isn't registered fails with a clear error; listing tasks by an unregistered tag is treated as a legitimate "nothing matches" query and returns an empty list instead. Register a project's tag in Zentra before using it here.Registry not (yet) deployed: tags are matched by exact string, after trimming whitespace — any free text is accepted, there is no enforced set, and asking for the wrong one returns an empty list rather than an error, same as this server behaved before the registry existed.
This is transparent to callers either way — the same tag input works in
both worlds. See the comment above resolveTagForWrite/resolveTagForFilter
in src/tag.ts for the mechanics, and for the condition under which the
legacy path can eventually be deleted.
Manual verification
There's no automated integration test against the live production API — that would require storing real credentials in CI. After setup, verify by hand:
Start a Claude Code session in each project you use this from.
In each, ask Claude to create a task via
zentra_task_create(it should infer thetagfrom the project you're in).Confirm each task appears correctly — right title, tag, status — on the Zentra web UI's task board.
Ask Claude to list and move a task via
zentra_task_list/zentra_task_moveand confirm the board reflects it.Ask Claude to create a Vault page via
zentra_vault_create_page, then attach a local file to it viazentra_vault_upload_attachment. Confirm the page and its attachment appear in the Vault on the web UI. Note thatfilePathis read on the machine running this server, not on Claude's side.Ask Claude to create a Vault page with
folderset to the name of an existing folder andtagset to a registered tag. Confirm the page lands under that folder, tagged, on the web UI.Ask Claude to list sprints via
zentra_sprint_listwithstatus: "OPEN", then create or move a task with that sprint's id assprintId. Confirm the task shows up in that sprint on the web UI.
Available Tools
3 toolszentra_task_createCreate a Zentra taskA
Creates a task on Zentra's production task board. tag identifies the project this task belongs to — infer it from your own working directory and always pass it explicitly; any text works, not just a fixed set of known projects. type defaults to TASK; use parentId to link a BUG/TASK to an EPIC or a SUBTASK to a TASK.
Inputs: title (required), tag, type, status, +3 more.
zentra_task_listList Zentra tasksA
Lists tasks from Zentra's production task board, optionally filtered by project tag and/or status. Omit tag to see tasks across all projects.
Inputs: tag, type, status, parentId.
zentra_task_moveMove a Zentra task to a new statusB
Updates an existing task's status by id.
Inputs: id (required), status (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools have clearly distinct purposes: create, list, and move (status update). There is no overlap in functionality, making it easy for an agent to select the right operation.
All tool names follow the identical pattern `zentra_task_<verb>` with snake_case. This consistent verb_noun structure makes the API predictable and easy to navigate.
At 3 tools, the server is concise but not under-powered for a focused task management use case. The count is within the well-scoped range, though slightly lean.
The set covers the core lifecycle: creation, listing/filtering, and status transitions. Missing operations like full detail retrieval or deletion are minor gaps that can often be worked around via listing, but a dedicated get/update would improve completeness.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for generating rough-draft project plans from natural-language prompts.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that connects Claude with Todoist for complete task and project management through natural language.86203 npm246MIT
- AlicenseNot gradedqualityDmaintenanceAn OAuth-authenticated MCP server that bridges Claude AI with a task management system, allowing users to list, create, and update tasks through natural language commands.1ISC
- AlicenseAqualityDmaintenanceMCP server that exposes NirvanaHQ (GTD task manager) to Claude Code, enabling task management and project tracking through natural language.157 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for managing Kaiten tasks through AI agents like Claude, enabling task retrieval, creation, updating, and time logging.2ISC