timepiece-mcp

An MCP server that lets Claude query OBSS Timepiece Time in Status data for Jira issues.

Ask Claude things like:

• "How long has PROJ-123 spent in each status?"
• "Show me the full lifecycle of PROJ-456 including how many times it went back into Development"
• "What is the average cycle time for tickets closed this sprint?"
• "Which status is causing the biggest delays in our project?"
• "Export a CSV of time-in-status for all tickets resolved this month"

---

Prerequisites

• uv — fast Python package manager
• A Jira instance with Timepiece installed
• A personal Timepiece API token (see below)

Get your Timepiece API token

1. In Jira, go to Apps → Timepiece → API Settings
2. Click Create New Token
3. Copy the token

⚠️ Keep this token secret — it grants access to your Jira data through Timepiece.

---

Installation

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "timepiece": {
      "command": "uvx",
      "args": ["timepiece-mcp"],
      "env": {
        "TIMEPIECE_TOKEN": "your-token-here",
        "TIMEPIECE_CALENDAR": "your-calendar-id"
      }
    }
  }
}

Restart Claude Desktop. You'll see a 🔌 icon confirming the server is connected.

Claude Code (CLI)

claude mcp add timepiece uvx timepiece-mcp \
  -e TIMEPIECE_TOKEN=your-token-here \
  -e TIMEPIECE_CALENDAR=your-calendar-id

---

Environment variables

Variable	Required	Default	Description
TIMEPIECE_TOKEN	✅ Yes	—	Your personal Timepiece API token
TIMEPIECE_CALENDAR	Recommended	—	Default calendar ID for business-hours calculations. Without this, durations use a 24h/day UTC clock and will be wrong for most teams.
TIMEPIECE_DEFAULT_DAY_LENGTH	No	businessDays	businessDays or calendarDays
TIMEPIECE_DEFAULT_VIEW_FORMAT	No	days	days, hours, minutes, or seconds

Finding your calendar ID: In Jira go to Apps → Timepiece → Settings → Calendars. The numeric ID is shown next to each calendar. You can also ask Claude to run timepiece_list_calendars after setup to see all available calendars and their IDs.

---

Available tools

Tool	What it does
timepiece_get_issue	Time spent in each status for a single issue — returned as a Status / Duration / Visits table
timepiece_get_issue_expanded	Full status history for a single issue: visit counts, min/max/average per status, and a chronological transition timeline
timepiece_list_issues	Time-in-status for a set of issues defined by a JQL query, returned as an issues × statuses matrix
timepiece_aggregate	Average, median, sum or standard deviation of time-in-status across any JQL-filtered set of issues; also supports lead time and cycle time calculations
timepiece_list_calendars	Lists all Timepiece calendars configured for your Jira instance, including IDs, timezones and working hours
timepiece_search_calendar	Finds a calendar by name and returns its ID
timepiece_export_sync	Exports a time-in-status report as CSV or XLSX for any JQL-filtered set of issues, saving the file locally

---

Example prompts

How long did PROJ-123 spend in each status?
Show me the full lifecycle of PROJ-456 including how many times it went back into Development
What is the average cycle time for tickets closed in PROJ this sprint?
Which status is causing the biggest delays in project PROJ?
Compare average development time across the team for last sprint
Export a CSV of time-in-status for all PROJ tickets resolved this month
What calendars are configured in Timepiece?

---

Sharing with your team

Each team member needs their own Timepiece token:

1. Get a token from Jira → Apps → Timepiece → API Settings
2. Add the config block above to their Claude Desktop or Claude Code config
3. Use their own token — tokens are personal and tied to each person's Jira identity

---

Local development

git clone https://github.com/gianni1989/timepiece-mcp
cd timepiece-mcp
cp .env.example .env   # fill in your token and calendar ID
uv sync
uv run timepiece-mcp

Run the test suite:

TIMEPIECE_TOKEN=your-token TIMEPIECE_CALENDAR=your-calendar-id uv run python test_tools.py

---

Troubleshooting

"TIMEPIECE_TOKEN environment variable is not set" → Add TIMEPIECE_TOKEN to the env block in your Claude config and restart.

"Unauthorised — your TIMEPIECE_TOKEN is invalid or expired" → Go to Jira → Apps → Timepiece → API Settings and generate a new token.

"Not found — the issue key does not exist" → Verify the issue key format: it must be PROJECT-NUMBER in uppercase, e.g. PROJ-123.

Durations seem too large (e.g. 3× bigger than expected) → Set TIMEPIECE_CALENDAR to your calendar's numeric ID. Without it, the API uses a 24h/day UTC clock instead of your business hours.