Timetagger MCP

🚀 Time Tagger MCP Server

This is a Model Context Protocol (MCP) server for interacting with TimeTagger. It provides tools for querying and managing your time records, which can be used via Claude or other MCP-compatible AI assistants.

🚀 Quick Start

This server allows you to query and manage your time records effectively. You can use it with Claude or other MCP-compatible AI assistants.

✨ Features

• Query time records within a specific time period.
• Create new time records.
• Update existing records.
• Hide/delete records.
• Get time summaries by tag.
• Start and stop timers.
• Manage TimeTagger settings.

📦 Installation

Installation for Claude Desktop

Add the following content to your claude_desktop_config.json file:

"timetagger": {
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/regismesquita/timetagger-mcp",
    "timetagger-mcp"
  ],
  "env": {
    "TIMETAGGER_API_KEY": "your-api-key-here",
    "TIMETAGGER_API_URL": "https://your-timetagger-instance.com/api/v2"
  }
}

Manual Installation

1. Make sure uv is installed:

   brew install uv
   

2. Install the required dependencies:

   uv pip install -r requirements.txt
   

Configuration

The server requires you to set the TimeTagger API key as an environment variable:

export TIMETAGGER_API_KEY="your-api-key-here"
export TIMETAGGER_API_URL="https://your-timetagger-instance.com/api/v2"

💻 Usage Examples

Basic Usage

Run in Development Mode

For testing and development:

fastmcp dev timetagger_mcp.py

This will launch the MCP checker interface where you can test tools and resources.

Install to Claude Desktop

To use it with Claude Desktop:

fastmcp install timetagger_mcp.py

Available Tools

• get_records(start_time, end_time): Get records within a specific time period.
• get_recent_records(hours): Get records from the past N hours.
• get_today_records(): Get records for the current day.
• create_record(description, start_time, end_time): Create a new record.
• update_record(key, description, start_time, end_time): Update an existing record.
• hide_record(key): Hide/delete a record.
• start_timer(description): Start a new timer.
• stop_timer(key): Stop a running timer.
• find_records_by_tag(tag, days): Find records by tag.
• get_time_summary(days): Get a time summary for the past N days.
• get_settings(): Get all TimeTagger settings.
• update_setting(key, value): Update a specific TimeTagger setting.

Available Resources

• timetagger://config: Get the TimeTagger configuration.
• timetagger://records/{timerange}: Get records within a specific time period.
• timetagger://settings: Get all settings.
• timetagger://updates/{since}: Get updates since a certain timestamp.