TimeTagger MCP Server

This is a Model Context Protocol (MCP) server for interacting with TimeTagger. It provides tools to query and manage your time records through Claude or other MCP-compatible AI assistants.

Features

• Query time records within specific timeframes
• Create new time records
• Update existing records
• Hide/delete records
• Get time summaries by tags
• Start and stop timers
• Manage TimeTagger settings

Claude Desktop Installation

Add this to your `claude_desktop_config.json`:

"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. Ensure you have uv installed:

brew install uv

2. Install the required dependencies:

uv pip install -r requirements.txt

Configuration

The server requires your TimeTagger API key to be set as an environment variable:

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

Usage

Running in Development Mode

For testing and development, use:

fastmcp dev timetagger_mcp.py

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

Installing for Claude Desktop

To use with Claude Desktop:

fastmcp install timetagger_mcp.py

Available Tools

• `get_records(start_time, end_time)`: Get records within a time range
• `get_recent_records(hours)`: Get records from the last N hours
• `get_today_records()`: Get today's records
• `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 an ongoing timer
• `find_records_by_tag(tag, days)`: Find records with a specific tag
• `get_time_summary(days)`: Get a summary of time spent on different tags
• `get_settings()`: Get all TimeTagger settings
• `update_setting(key, value)`: Update a TimeTagger setting

Available Resources

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