README.md
Integrates with the EARLY (Timeular v4) API to manage activities and track time.
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.
Tools (14)
list_activitiesList all activities with IDs, names, and colorscreate_activityCreate a new activityupdate_activityUpdate an existing activity's name or colordelete_activityArchive/delete an activitycurrent_trackingGet the currently running timerstart_trackingStart tracking time for an activitystop_trackingStop the current trackerlist_time_entriesQuery time entries within a date rangecreate_time_entryCreate a manual time entrydelete_time_entryDelete a time entrytime_summaryAggregate hours by activity for a periodefficiency_reportAnalyze time distribution and detect untracked gapsbilling_reportCalculate billable hours and cost by activityexplore_apiMake raw authenticated requests to any EARLY API endpointEnvironment Variables
EARLY_API_KEYrequiredYour EARLY developer API keyEARLY_API_SECRETrequiredYour EARLY developer API secretConfiguration
claude_desktop_config.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"}}}}Try it
→What is the current activity I am tracking right now?
→Generate a billing report for all activities completed this week.
→Start tracking time for the 'Development' activity.
→Analyze my time distribution for the last month and identify any untracked gaps.
→List all my current activities and their associated IDs.