# everhour-mcp-server

MCP server for [Everhour](https://everhour.com) 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:**
   ```bash
   npm install
   npm run build
   ```

3. **Run locally with the MCP Inspector:**
   ```bash
   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`:

```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`):

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