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

Tools

Tool	Description
`list_activities`	List all activities with IDs, names, and colors
`create_activity`	Create a new activity
`update_activity`	Update an existing activity's name or color
`delete_activity`	Archive/delete an activity
`current_tracking`	Get the currently running timer
`start_tracking`	Start tracking time for an activity
`stop_tracking`	Stop the current tracker
`list_time_entries`	Query time entries within a date range
`create_time_entry`	Create a manual time entry
`delete_time_entry`	Delete a time entry
`time_summary`	Aggregate hours by activity for a period
`efficiency_report`	Analyze time distribution and detect untracked gaps
`billing_report`	Calculate billable hours and cost by activity
`explore_api`	Make raw authenticated requests to any EARLY API endpoint

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

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
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.

Early MCP