tempo-mcp

MCP server that lets Claude log, list, and delete Tempo worklogs against Jira issues.

Setup

1. npm install && npm run build

2. Copy .env.example to .env and fill in:

   • TEMPO_API_TOKEN — generated in Jira under Tempo → Settings → API Integration, scoped to Manage Worklogs.

   • JIRA_BASE_URL — e.g. https://your-domain.atlassian.net

   • JIRA_EMAIL / JIRA_API_TOKEN — used to resolve issue keys (e.g. PROJ-1234) to the numeric issue IDs Tempo requires. Generate the token at https://id.atlassian.com/manage-profile/security/api-tokens.

Related MCP server: JIRA MCP Server

Register with Claude Code

claude mcp add tempo-mcp -- node /path/to/tempo-mcp/dist/index.js

Or via .mcp.json, with the env vars above set in the entry's env block.

The server validates both Tempo and Jira credentials on startup and logs a clear pass/fail message to stderr (visible in Claude Code's MCP logs) before it accepts tool calls, rather than failing confusingly on first use.

Tools

Worklogs

• get_worklogs — list worklogs, optionally filtered by issueKey, authorAccountId, and date range (from/to).

• post_worklog — log time against an issue (issueKey, timeSpentHours or timeSpentSeconds, startDate, authorAccountId, optional startTime/description). Defaults to a dry-run preview; pass confirm: true to actually write it.

• update_worklog — change an existing worklog's time/date/description by tempoWorklogId. Same dry-run/confirm: true behavior.

• delete_worklog — delete a worklog by tempoWorklogId. Same dry-run/confirm: true behavior (previews the real worklog before deleting it).

Lookups (so Claude doesn't need issue IDs or account IDs handed to it up front)

• whoami — the Jira account the configured credentials belong to.

• search_projects — list/filter visible Jira projects.

• search_recent_issues — find issues by project, assignee, and/or free text, most recently updated first.

post_worklog requires an authorAccountId. Get your own via whoami; for others, use their Jira admin console profile URL, which shows their accountId. (An earlier find_users tool was removed — it depended on the "Browse users and groups" global permission, which returned an empty result with HTTP 200 rather than an error when missing, confirmed via direct API testing against this org's Jira instance.)

Issue keys are resolved to Tempo's required numeric issue ID automatically (and cached in-process) via the Jira REST API. Auth failures return a plain-English hint (e.g. "check JIRA_EMAIL/JIRA_API_TOKEN/JIRA_BASE_URL") instead of a raw, sometimes localized, HTTP error body.

Safety and abuse controls

• authorAccountId is allowlisted, not free-form. post_worklog will only attribute a worklog to the credentialed account (from JIRA_EMAIL/whoami) unless AUTHORIZED_AUTHOR_ACCOUNT_IDS in .env explicitly lists other account IDs. This exists specifically so that content Claude reads from a Jira issue or Tempo worklog description can't talk it into logging fabricated time against an arbitrary third party — the allowlist is controlled by you, in .env, not by anything the model reads.

• Every write is dry-run by default. post_worklog, update_worklog, and delete_worklog all preview what they would do and require an explicit confirm: true to actually execute.

• MAX_WRITES_PER_SESSION (default 20) caps how many writes a single running server process will perform before refusing further ones, as a blast-radius limit against a runaway or manipulated conversation. Restart the server to reset the count.

• Local audit log. Every post_worklog/update_worklog/delete_worklog call (success or failure) is appended as a JSON line to logs/audit.jsonl (gitignored) — a local record of what was written, independent of Tempo's own history.

• Keep .env file permissions restricted, especially on a shared machine — it holds both the Tempo API token and Jira Basic-auth credentials in plaintext.