zentra-mcp

MCP server exposing Zentra's Task API as tools Claude can call directly — zentra_task_create, zentra_task_list, zentra_task_move — from any project, not just from inside the Zentra repo.

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 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 and builds dist/ if either is missing, then execs the server. That matters for fresh checkouts, where MCP stdio servers are spawned before anything has had a chance to build. Build output goes to stderr so stdout stays a clean protocol channel.

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. Any free text is accepted — there is no enforced set. Tags are matched by exact string, so MyProject and myproject are different tags, and asking for the wrong one returns an empty list rather than an error. Pick a convention and hold to it.

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.