Skip to main content
Glama
timepiece-mcp

timepiece-mcp

by gianni1989

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)

Related MCP server: Jira Cloud MCP Server

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.

Available Tools

7 tools
timepiece_aggregateA
Read-onlyIdempotent

Aggregate time-in-status statistics across multiple Jira issues.

Computes average, median, sum, or standard deviation of time spent in each status across all issues matching the JQL query.

Args: params (AggregateInput): Validated input containing: - aggregation_type (str): 'average', 'sum', 'median', or 'standardDeviation' - jql (str): JQL query to select issues - columns_by (str): Column grouping (default: statusDuration) - calendar (Optional[str]): Timepiece calendar ID or name - day_length (str): 'businessDays' or 'calendarDays' (default: businessDays) - view_format (str): 'days', 'hours', 'minutes', 'seconds' (default: days) - statuses (Optional[str]): Comma-separated status IDs to filter - dbs_metrics (Optional[str]): JSON for duration-between-statuses metrics - response_format (str): 'markdown' or 'json' (default: markdown)

Returns: str: Aggregated time-in-status statistics as a Markdown table or JSON.

Inputs: params (required). Returns: result

timepiece_export_syncA
Read-only

Export time-in-status data for Jira issues to a downloadable file.

Generates an XLSX or CSV export of time-in-status data for issues matching the JQL query and saves it to /tmp. Returns the file path and a summary.

Args: params (ExportSyncInput): Validated input containing: - jql (str): JQL query to select issues - output_type (str): 'xlsx' or 'csv' - columns_by (str): Column grouping (default: statusDuration) - calendar (Optional[str]): Timepiece calendar ID or name - day_length (str): 'businessDays' or 'calendarDays' (default: businessDays) - view_format (str): 'days', 'hours', 'minutes', 'seconds' (default: days) - statuses (Optional[str]): Comma-separated status IDs to include

Returns: str: File path of the exported file and a summary of the export.

Inputs: params (required). Returns: result

timepiece_get_issueA
Read-onlyIdempotent

Get time-in-status data for a single Jira issue from Timepiece.

Returns how long the issue has spent in each workflow status (e.g. To Do, In Progress, In Review, Done), using a configurable calendar and time unit.

Args: params (GetIssueInput): Validated input containing: - issue_key (str): Jira issue key, e.g. 'PROJ-123' - columns_by (str): 'statusDuration' or 'assigneeDuration' (default: statusDuration) - calendar (Optional[str]): Timepiece calendar ID or name - day_length (str): 'businessDays' or 'calendarDays' (default: businessDays) - view_format (str): 'days', 'hours', 'minutes', 'seconds' (default: days) - statuses (Optional[str]): Comma-separated status IDs to filter - response_format (str): 'markdown' or 'json' (default: markdown)

Returns: str: Time-in-status data as Markdown table (default) or JSON.

Examples: - "How long has PROJ-123 been in each status?" → issue_key='PROJ-123' - "Show PROJ-456 time in status in hours" → issue_key='PROJ-456', view_format='hours' - "Get calendar days for PROJ-789" → day_length='calendarDays'

Inputs: params (required). Returns: result

timepiece_get_issue_expandedA
Read-onlyIdempotent

Get expanded time-in-status data including full transition history for a single Jira issue.

Returns per-status statistics (total days, visit count, average per visit) plus a chronological list of every status transition with its duration.

Args: params (GetIssueExpandedInput): Validated input containing: - issue_key (str): Jira issue key, e.g. 'PROJ-123' - calendar (Optional[str]): Timepiece calendar ID or name - day_length (str): 'businessDays' or 'calendarDays' (default: businessDays) - view_format (str): 'days', 'hours', 'minutes', 'seconds' (default: days) - trim_history_start_date (Optional[str]): Earliest date to include (yyyy-MM-dd) - trim_history_end_date (Optional[str]): Latest date to include (yyyy-MM-dd) - response_format (str): 'markdown' or 'json' (default: markdown)

Returns: str: Expanded time-in-status with summary stats and transition history table.

Inputs: params (required). Returns: result

timepiece_list_calendarsA
Read-onlyIdempotent

List all available Timepiece calendars.

Returns all configured calendars in your Timepiece instance, including their IDs, names, timezones, and working hours settings. Use calendar IDs when querying time-in-status data.

Args: params (ListCalendarsInput): Optional response format ('markdown' or 'json').

Returns: str: Table of calendars with ID, name, timezone, working hours, and default flag.

Inputs: params (required). Returns: result

timepiece_list_issuesA
Read-onlyIdempotent

List time-in-status data for multiple Jira issues selected by JQL query.

Uses the Timepiece list API to fetch time-in-status for all issues matching the JQL filter. Results are presented as a table with one row per issue.

Args: params (ListIssuesInput): Validated input containing: - jql (str): JQL query to select issues - columns_by (str): Column grouping (default: statusDuration) - calendar (Optional[str]): Timepiece calendar ID or name - day_length (str): 'businessDays' or 'calendarDays' (default: businessDays) - view_format (str): 'days', 'hours', 'minutes', 'seconds' (default: days) - statuses (Optional[str]): Comma-separated status IDs to filter - page_size (int): Results per page (1-1000, default 100) - response_format (str): 'markdown' or 'json' (default: markdown)

Returns: str: Table of issues with time-in-status per status column.

Inputs: params (required). Returns: result

timepiece_search_calendarA
Read-onlyIdempotent

Search for Timepiece calendars by name.

Useful for finding a calendar's numeric ID when you only know its name, e.g. 'Default Calendar Settings'.

Args: params (SearchCalendarInput): Validated input containing: - name (str): Calendar name to search for - search_type (str): 'exact' (default) or 'contain' - max_results (int): Maximum results to return (default 10) - response_format (str): 'markdown' or 'json' (default: markdown)

Returns: str: Matching calendars with ID, name, timezone, working hours, and default flag.

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools are clearly distinct, but `get_issue` and `get_issue_expanded` overlap as both retrieve per-issue time-in-status. The expanded version adds transition history, making it distinguishable, but an agent might still confuse them.

    Naming Consistency5/5

    All tools follow a consistent `timepiece_<verb>_<noun>` pattern (e.g., get_issue, list_issues, aggregate, export_sync). Even `get_issue_expanded` fits the pattern. No mixing of styles or inconsistencies.

    Tool Count5/5

    With 7 tools, the scope is well-calibrated for a time-in-status query and export server. Each tool serves a distinct purpose without unnecessary bloat or missing essential functions.

    Completeness4/5

    The core read/query use cases are covered: single issue, expanded details, bulk listing, aggregation, calendar management, and export. Minor gaps exist, such as no direct tool for fetching a single calendar by ID, but the overall surface is adequate for the server's stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for interacting with Jira Cloud instances. Enables issue management, JQL queries, project and sprint management, and batch operations via natural language interfaces.
      141 npm
      4
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Jira Server/Data Center, enabling issue management, comments, attachments, JQL search, and more through natural language.
      -