everhour-mcp-server

MCP server for Everhour time tracking, with first-class support for logging hours against Asana tickets.

Asana tasks synced into Everhour have IDs of the form as:<asanaGid>. The server exposes tools to look them up, log time, run timers, and review timesheets — both directly via Everhour task IDs and via raw Asana GIDs.

Tools

Tool	Purpose
everhour_get_current_user	Verify the API key and read your Everhour user ID
everhour_list_projects	List/search projects, filterable by platform (e.g. asana)
everhour_get_project	Fetch a project by ID
everhour_search_tasks	Find Everhour tasks by name (also matches synced Asana tasks)
everhour_get_task	Fetch a task by Everhour ID
everhour_find_task_by_asana_id	Resolve an Asana task GID → Everhour task
everhour_log_time	Log hours on an Everhour task
everhour_log_time_for_asana_task	Log hours given an Asana GID (workflow shortcut)
everhour_log_time_batch	Log many entries at once (day/week/month), with per-row results
everhour_list_time_records	Review your timesheet (date range, project, task filters)
everhour_update_time_record	Edit an existing time record
everhour_delete_time_record	Delete a time record
everhour_start_timer	Start the active timer on a task
everhour_stop_timer	Stop the active timer
everhour_get_current_timer	Check whether a timer is running

Setup

1. Get your Everhour API key: profile → Settings → API integration: https://app.everhour.com/#/account/profile

2. Install & build:

   npm install
   npm run build
   

3. Run locally with the MCP Inspector:

   EVERHOUR_API_KEY=ev_xxx npm run inspect
   

Configure for Claude Code / Claude Desktop

Add an entry under mcpServers in your client config. For Claude Desktop on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "everhour": {
      "command": "node",
      "args": ["/absolute/path/to/mcp everhour/dist/index.js"],
      "env": {
        "EVERHOUR_API_KEY": "ev_your_personal_api_key"
      }
    }
  }
}

For Claude Code (~/.claude.json or .claude/settings.json):

{
  "mcpServers": {
    "everhour": {
      "command": "node",
      "args": ["/absolute/path/to/mcp everhour/dist/index.js"],
      "env": { "EVERHOUR_API_KEY": "ev_..." }
    }
  }
}

Restart the client. The 15 tools listed above will appear.

Typical workflows

Log time on an Asana ticket from its URL. The user pastes https://app.asana.com/0/1234567890/1208034567890123 and says "log 2 hours, fixed the retry bug":

1. Extract the GID 1208034567890123 from the URL.
2. Call everhour_log_time_for_asana_task with asana_task_gid=1208034567890123, duration={ hours: 2 }, comment="fixed the retry bug".

Find a task by name and start tracking.

1. everhour_search_tasks with query="login bug".
2. Pick the right task ID (as:1208...) from results.
3. everhour_start_timer with that task_id.
4. Later: everhour_stop_timer.

Review what you logged this week.

everhour_list_time_records with from=YYYY-MM-DD (Mon), to=YYYY-MM-DD (Sun).

Daily logging workflow (log-everhour skill)

The .claude/skills/log-everhour/ skill logs a day, week, or month of Asana-ticket work in one pass. You give per-day entries (ticket + hours + a rough comment); it resolves each ticket, rephrases the comments to the Time Registration Guidelines (.claude/skills/log-everhour/rephrasing-rules.md), normalizes hours to 30-minute increments, warns about duplicates, shows a preview table, and logs everything via everhour_log_time_batch after a single confirmation.

Notes on Asana sync

Everhour pulls Asana tasks via the official integration. A task is only visible in Everhour after:

• The Asana project has been added in Everhour (Settings → Integrations → Asana), or
• A user with the Everhour browser extension opens the task in Asana.

If everhour_find_task_by_asana_id returns a 404, sync hasn't happened yet.

Environment variables

Var	Required	Description
EVERHOUR_API_KEY	yes	Personal Everhour API key

License

MIT