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:

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)

1. Install and build:

   yarn install && yarn build

2. Authenticate. 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 login

   This writes a JWT to ~/.config/zentra-mcp/credentials.json (mode 600). The JWT expires after 7 days; re-run when a tool call reports "Session expired."

   Unattended — set ZENTRA_TOKEN to a long-lived service token, which takes precedence over the credentials file. This is how the scheduled daily runs authenticate; see docs/service-token.md in the Zentra repo for how to mint one.

3. 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.sh installs dependencies when node_modules is missing and builds when dist/ is missing or stale (any src/*.ts newer than dist/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 every git pull, since an out-of-date dist/ 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 tag name 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:

1. Start a Claude Code session in each project you use this from.

2. In each, ask Claude to create a task via zentra_task_create (it should infer the tag from the project you're in).

3. Confirm each task appears correctly — right title, tag, status — on the Zentra web UI's task board.

4. Ask Claude to list and move a task via zentra_task_list/zentra_task_move and confirm the board reflects it.

5. Ask Claude to create a Vault page via zentra_vault_create_page, then attach a local file to it via zentra_vault_upload_attachment. Confirm the page and its attachment appear in the Vault on the web UI. Note that filePath is read on the machine running this server, not on Claude's side.

6. Ask Claude to create a Vault page with folder set to the name of an existing folder and tag set to a registered tag. Confirm the page lands under that folder, tagged, on the web UI.

7. Ask Claude to list sprints via zentra_sprint_list with status: "OPEN", then create or move a task with that sprint's id as sprintId. Confirm the task shows up in that sprint on the web UI.