Tempo MCP Server

MCP (Model Context Protocol) server for Tempo time tracking with full support for roles and accounts.

Features

• Auto-generate timesheets from git commits - scans all your repos and creates worklogs automatically
• Create worklogs with role and account attributes
• Automatically fetch account from Jira issue
• Auto-fallback to active account when issue's account is closed/archived
• Quick sprint meeting logging - just specify project and minutes
• Update and delete worklogs
• List worklogs for date ranges
• Get available work attributes and roles

Installation

npm install
npm run build

Configuration

Getting your API tokens

Tempo API Token:

1. Go to Tempo > Settings in your Jira instance
2. Click on API Integration in the left sidebar
3. Click New Token
4. Give it a name (e.g., "Claude Code MCP")
5. Select permissions: Manage Worklogs (or Full Access)
6. Copy the generated token

Jira API Token:

1. Go to Atlassian API Tokens
2. Click Create API token
3. Give it a label (e.g., "Claude Code MCP")
4. Copy the generated token

Environment Variables

Variable	Required	Description
TEMPO_API_TOKEN	Yes	Tempo API token (get from Tempo > Settings > API Integration)
JIRA_API_TOKEN	Yes	Jira API token (get from id.atlassian.com/manage-profile/security/api-tokens)
JIRA_EMAIL	Yes	Jira account email
JIRA_BASE_URL	Yes	Jira base URL (e.g., https://company.atlassian.net)
JIRA_ACCOUNT_FIELD_ID	No	Custom field ID for Tempo account (default: 10026)
DEFAULT_ROLE	No	Default role for worklogs (default: Dev)
DEFAULT_PROJECTS_DIR	No	Default directory for git repos (e.g., C:/Users/you/Projects)
DEFAULT_MONDAY_MEETING_ISSUE	No	Jira issue for Monday team meeting (default: BS-14)

Note: gitAuthor defaults to JIRA_EMAIL since they're the same for all developers.

Usage with Claude Code

Quick Setup (one command)

Linux/macOS:

claude mcp add tempo-mcp -s user \
  -e TEMPO_API_TOKEN=your-tempo-token \
  -e JIRA_API_TOKEN=your-jira-token \
  -e JIRA_EMAIL=your-email@company.com \
  -e JIRA_BASE_URL=https://company.atlassian.net \
  -e DEFAULT_PROJECTS_DIR=/home/you/projects \
  -- npx -y github:Henry-Workshop/tempo-mcp

Windows (PowerShell):

claude mcp add tempo-mcp -s user `
  -e TEMPO_API_TOKEN=your-tempo-token `
  -e JIRA_API_TOKEN=your-jira-token `
  -e JIRA_EMAIL=your-email@company.com `
  -e JIRA_BASE_URL=https://company.atlassian.net `
  -e DEFAULT_PROJECTS_DIR=C:/Users/you/Projects `
  -- npx.cmd -y github:Henry-Workshop/tempo-mcp

Example configuration in claude.json

{
  "mcpServers": {
    "tempo-mcp": {
      "command": "npx",
      "args": ["-y", "github:Henry-Workshop/tempo-mcp"],
      "env": {
        "TEMPO_API_TOKEN": "your-tempo-token",
        "JIRA_API_TOKEN": "your-jira-token",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_BASE_URL": "https://company.atlassian.net",
        "DEFAULT_PROJECTS_DIR": "C:/Users/you/Projects"
      }
    }
  }
}

Available Tools

tempo_generate_timesheet

The main feature! Automatically generate your weekly timesheet from git commits.

{
  "weekStart": "2025-12-01",
  "gitAuthor": "your-email@company.com",
  "projectsDir": "C:/Users/you/Projects",
  "dryRun": true,
  "mondayMeetingIssue": "BS-14"
}

Parameter	Required	Description
weekStart	Yes	Monday date of the week (YYYY-MM-DD)
gitAuthor	Yes	Your git author email or name
projectsDir	Yes	Directory containing all your git repositories
dryRun	No	If true, shows plan without creating worklogs (default: false)
mondayMeetingIssue	No	Jira issue for Monday team meeting (default: BS-14)

What it does:

1. Scans all git repos in projectsDir
2. Extracts your commits for Monday-Thursday
3. Parses Jira issue keys from commit messages (e.g., PROJ-123)
4. Distributes 8h/day based on commit count per issue
5. Adds 15min daily sprint meeting (on the main project of the day)
6. Adds 15min Monday team sync on BS-14
7. Generates client-friendly descriptions from commit messages
8. Creates worklogs in Tempo

Example usage in Claude Code:

• "fait ma feuille de temps de cette semaine"
• "generate my timesheet for last week"
• "do my timesheet for the week of december 1st in dry run mode"

Important: Your commit messages should include Jira issue keys (e.g., PROJ-123 fix: description). Commits without issue keys will be flagged as warnings.

---

tempo_log_sprint_meeting

Quick way to log time for sprint meetings (daily, planning, retro). Automatically finds the "Sprint Meetings" issue for the project.

{
  "projectKey": "PROJ",
  "timeSpentMinutes": 15,
  "description": "Daily",
  "date": "2025-11-27"
}

Example usage in Claude Code:

• "add 15 mins for sprint meetings for BERGA"
• "log daily 15 mins to CRC project"

tempo_create_worklog

Create a new worklog with role and account support.

{
  "issueKey": "PROJ-123",
  "timeSpentHours": 1.5,
  "date": "2025-11-27",
  "description": "Working on feature",
  "role": "Dev",
  "accountKey": "ACCOUNT-KEY"
}

If accountKey is not provided, it will be automatically fetched from the Jira issue. If the account is closed/archived, it will automatically find an active account from recent project issues.

tempo_get_worklogs

Retrieve worklogs for a date range.

{
  "startDate": "2025-11-01",
  "endDate": "2025-11-30"
}

tempo_update_worklog

Update an existing worklog.

{
  "worklogId": "12345",
  "timeSpentHours": 2,
  "description": "Updated description"
}

tempo_delete_worklog

Delete a worklog.

{
  "worklogId": "12345"
}

tempo_get_work_attributes

Get available work attributes (roles, accounts configuration).

tempo_get_roles

Get available Tempo roles.

License

MIT