EARLY MCP Server

An MCP (Model Context Protocol) server that integrates with the EARLY (Timeular v4) time tracking API. Gives AI assistants like Claude full access to time tracking, activity management, and analytics.

Features

• Activity Management - Create, update, list, and delete activities

• Time Tracking - Start/stop timers, view current tracking status

• Time Entries - Query, create, and delete manual time entries

• Analytics - Time summaries, efficiency reports with gap detection, and billing reports

• API Explorer - Raw authenticated access to any EARLY API endpoint

Related MCP server: TrackingTime MCP Server

Tools

Setup

Prerequisites

• Python 3.12+

• uv package manager

• An EARLY developer API key and secret

Install

git clone git@github.com:sakebomb/early_mcp.git
cd early_mcp
uv sync

Configuration

Create a .env file with your EARLY API credentials:

EARLY_API_KEY=your_api_key
EARLY_API_SECRET=your_api_secret

Optional settings:

Tool hints

Every tool declares MCP annotations so clients can decide what to confirm. Tools that can lose tracked time are marked destructive: deleting or editing an entry, cancelling a timer, and also creating an entry or stopping a timer, because EARLY splits or removes existing entries that a new one overlaps. explore_api is advertised read-only unless writes are enabled.

Dates and timezones

The EARLY API stores timestamps in UTC without an offset. Tools take dates (YYYY-MM-DD) and naive timestamps as local time in EARLY_TIMEZONE and convert them to UTC, so a "day" means your local day. Timestamps with an explicit offset (+01:00, Z) are converted from that offset. Raw entries returned by list_time_entries keep EARLY's UTC timestamps; report tools group by local day.

Stopping a timer

EARLY rejects a stop less than one minute after the start and discards the timer along with it, so stop_tracking checks the timer's age first and leaves a younger one running. With round_minutes, both ends of the entry are snapped to the nearest step (on the UTC grid) after the stop. A neighbouring entry off that grid, for example one made in the app, would then overlap and EARLY would split or remove it, so the rounded span is clamped to its neighbours, and it keeps its exact times if under a minute would remain.

Command line

early_cli.py runs the same tools from a hook or timer, printing JSON:

uv run python early_cli.py stop --round 15 --folder <folder_id>   # only stops a timer in that folder
uv run python early_cli.py timesheet 2026-10-17 2026-10-30 --folder <folder_id>

Claude Code

Add this to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "early": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/early_mcp", "python", "early.py"],
      "env": {
        "EARLY_API_KEY": "your_api_key",
        "EARLY_API_SECRET": "your_api_secret"
      }
    }
  }
}

Project Structure

early.py          # MCP server with tool definitions
early_client.py   # API client, auth, and utility functions
early_cli.py      # Command-line entry for hooks and timers
tests/            # pytest suite (mocked HTTP; run with `uv run pytest`)
pyproject.toml    # Project config and dependencies

Authentication

The server uses EARLY's developer sign-in flow. It exchanges your API key/secret for a bearer token, caches it in memory, and automatically refreshes on expiry.