Tempo MCP Server

🚀 Tempo MCP Server

This is an MCP server designed to manage Tempo work logs in Jira. It offers tools for time tracking and work log management via the Tempo API and can be accessed through clients like Claude, Cursor, and others compatible with the MCP protocol.

🚀 Quick Start

This MCP server is used to manage Tempo work logs in Jira. It provides tools for time tracking and work log management through the Tempo API and can be accessed via clients such as Claude, Cursor, and other MCP - protocol - compatible clients.

✨ Features

• Retrieve Work Logs: Fetch all work logs within a specific date range.
• Create Work Logs: Record time against Jira issues.
• Bulk Creation: Create multiple work logs in a single operation.
• Edit Work Logs: Modify the recorded time, date, and description.
• Delete Work Logs: Remove existing work logs.

📦 Installation

System Requirements

• Node.js 18+ (LTS version is recommended).
• A Jira Cloud instance.
• A Tempo API token.
• A Jira API token.

💻 Usage Examples

There are two main ways to use this MCP server:

Option 1: Using NPX (Recommended for Most Users)

The simplest way to use it via npx is to run it directly without installation.

Connecting to Claude Desktop (NPX Method)

1. Open your MCP client configuration file:
   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • On Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the following configuration:

{
  "mcpServers": {
    "Jira_Tempo": {
      "command": "npx",
      "args": [
        "@ivelin-web/tempo-mcp-server"
      ],
      "env": {
        "TEMPO_API_KEY": "your_tempo_api_key_here",
        "JIRA_SITE": "your_jira_site_url_here"
      }
    }
  }
}

3. After saving the file, your MCP server can be used through clients like Claude.

Option 2: Local Cloning

If you want to develop or customize the server, follow these steps:

1. Clone the repository locally:

git clone https://github.com/yourusername/tempo-mcp-server.git

2. Navigate to the project directory and install the dependencies:

cd tempo-mcp-server
npm install

3. Start the server for development:

npm run dev

📚 Documentation

Project Structure

tempo-mcp-server/
├── src/                  # Source code directory
│   ├── config.ts         # Configuration management file
│   ├── index.ts          # MCP server implementation file
│   ├── jira.ts           # Jira API integration file
│   ├── tools.ts          # Tool implementation file
│   ├── types.ts          # TypeScript type and schema definitions
│   └── utils.ts          # Utility function file
├── build/                # Compiled JavaScript code
├── tsconfig.json         # TypeScript configuration file
└── package.json          # Project metadata and script configuration

Tool Descriptions

Retrieve Work Logs (/list)

• Function: List all recorded work logs.
• Request Parameters:
  • worklogId: ID of a specific work log (optional).
• Return Value: A JSON array containing detailed work log information.

Create Work Logs (/create)

• Function: Create a new work log for a Jira issue.
• Request Parameters:
  • issueKey: The key of the issue to record time against.
  • timeSpentHours: A positive number representing the time spent (in hours).
  • date: The date of the work log in the format YYYY - MM - DD.
  • description: Description content (optional).

Bulk Create Work Logs (/bulk-create)

• Function: Create multiple work logs in a single operation.
• Request Parameters:
  • worklogEntries: An array containing the following attributes:
    • issueKey: The key of the issue to record time against.
    • timeSpentHours: A positive number representing the time spent (in hours).
    • date: The date of the work log in the format YYYY - MM - DD.
    • description: Description content (optional).

Edit Work Logs (/edit)

• Function: Modify an existing work log.
• Request Parameters:
  • worklogId: The ID of the work log to modify.
  • timeSpentHours: A positive number representing the new recorded time (in hours).
  • description: New description content (optional).
  • date: New date in the format YYYY - MM - DD (optional).

Delete Work Logs (/delete)

• Function: Delete a specified work log.
• Request Parameters:
  • worklogId: The ID of the work log to delete.

Error Handling and Debugging

If you encounter issues during use, follow these steps to troubleshoot:

1. Ensure that all environment variables are set correctly:

echo $TEMPO_API_KEY && echo $JIRA_SITE

2. Verify that your Tempo and Jira API tokens have the correct permissions. Generally, you need the following permissions:
   • Read and write permissions for issues.
   • Management permissions for work logs.
3. Check the error messages in the console output, which will help you locate the specific problem.
4. If the problem persists, try running the server in debug mode:

npm run inspect

📄 License

MIT

Credit

This server implements the Model Context Protocol specification created by Anthropic.